/**
 * cli:derive-change-impact — impact.ts
 *
 * The ORDERED downstream checklist of each kind — the heart of `/ba-change`,
 * as DATA. Each step names the file and the owning skill sub-workflow of an
 * authoring decision, or the derive-* CLI to run (contiguous literal path +
 * spec + whether it writes), the reason, and the audit rule(s) that sanction
 * the omission. Conditions the corpus cannot decide stay `conditional` with a
 * human `condition` — never a guessed verdict.
 *
 * Every `skills/business-analyse/…` path below is ONE contiguous literal: the
 * installer re-points it at the flattened `skills/ba-*` with a plain
 * String.replace (lib/remediation.ts doctrine; deploy-paths.test.ts locks it).
 * `skills/ba-develop/…` deploys as-is.
 */
import type { ParsedScreen } from '../../../../lib/ba-screens.js'
import { effectiveMode } from '../../../../lib/ba-screens.js'
import { FLOOR_BY_GRAIN, PERMISSION_ACTIONS, parsePermissionPath } from '../../../../lib/permission-actions.js'
import type { ScopeCorpus } from './corpus.js'
import { canonicalPortee } from './existing.js'
import type { Allocation, ChangeKind, ChangeOp, ChangeTarget, ExistingMatch, ExistingReport, ImpactStep, TraceReport } from './types.js'

export const CLI_PATHS = {
  deriveLookupGrants: 'skills/business-analyse/create-rbac/cli/derive-lookup-grants/index.ts',
  derivePermissionFloor: 'skills/business-analyse/create-rbac/cli/derive-permission-floor/index.ts',
  deriveRbacGrants: 'skills/business-analyse/create-rbac/cli/derive-rbac-grants/index.ts',
  deriveRuleLinks: 'skills/business-analyse/create-prd/cli/derive-rule-links/index.ts',
  deriveLifecycle: 'skills/business-analyse/create-prd/cli/derive-lifecycle/index.ts',
  deriveKanbanSpec: 'skills/business-analyse/create-prd/cli/derive-kanban-spec/index.ts',
  deriveUcCoverage: 'skills/business-analyse/create-screen/cli/derive-uc-coverage/index.ts',
  deriveRelatedTabs: 'skills/business-analyse/create-screen/cli/derive-related-tabs/index.ts',
  auditBa: 'skills/business-analyse/audit-run/cli/audit-ba/index.ts',
  sourcesSearch: 'skills/business-analyse/create-sources/cli/search/index.ts',
  deriveFormSections: 'skills/business-analyse/create-prd/cli/derive-form-sections/index.ts',
  deriveDetailSummary: 'skills/business-analyse/create-prd/cli/derive-detail-summary/index.ts',
  deriveCodeSpecs: 'skills/ba-develop/cli/derive-code-specs/index.ts',
  deriveFilterFks: 'skills/ba-develop/cli/derive-filter-fks/index.ts',
  deriveNavResources: 'skills/ba-develop/cli/derive-nav-resources/index.ts',
} as const

/** Mirror of `lib/detail-tab-strip.ts` PAGESPEC_FILENAME_RE (private there). */
export const PAGESPEC_FILENAME_RE = /^([A-Z][A-Za-z0-9]*)\.([a-z][a-z-]*)\.md$/

/**
 * The pagespec view a screen folds into (create-prd/SKILL.md § pagespecs):
 * list / form / detail / dashboard / app-home / module-home / section-home;
 * SmartKanban and SmartCard fold into the LIST pagespec (no file of their own).
 */
export function pagespecViewOf(screen: ParsedScreen): string | null {
  return pagespecViewFor(screen.screenType, effectiveMode(screen))
}

/** Expected `<Entity>.<view>.md` of a screen that does NOT exist yet (kind=screen). */
export function expectedPagespecNameFor(screenType: string, entity: string | undefined, mode: string | undefined): string | null {
  const view = pagespecViewFor(screenType, mode ?? 'edit')
  if (!view || !entity) return null
  const name = `${entity}.${view}.md`
  return PAGESPEC_FILENAME_RE.test(name) ? name : null
}

export function pagespecViewFor(screenType: string, mode: string): string | null {
  switch (screenType) {
    case 'SmartListView':
      return 'list'
    case 'SmartForm':
      return mode === 'detail' ? 'detail' : 'form'
    case 'SmartDashboard':
      return 'dashboard'
    case 'SmartAppHome':
      return 'app-home'
    case 'SmartModuleHome':
      return 'module-home'
    case 'SmartSectionHome':
      return 'section-home'
    default:
      return null
  }
}

/** Expected `<Entity>.<view>.md` name of a screen's pagespec — null when the type folds or has no entity. */
export function expectedPagespecName(screen: ParsedScreen): string | null {
  const view = pagespecViewOf(screen)
  if (!view || !screen.entity) return null
  const name = `${screen.entity}.${view}.md`
  return PAGESPEC_FILENAME_RE.test(name) ? name : null
}

/** The pagespec of an existing screen: joined on `screenCode` verbatim (authoritative), else the expected name. */
export function pagespecFor(corpus: ScopeCorpus, screen: ParsedScreen): { name: string | null; exists: boolean; joinedOnScreenCode: boolean } {
  const byCode = (corpus.pagespecs ?? []).find((p) => p.block && p.block['screenCode'] === screen.code)
  if (byCode) return { name: byCode.name, exists: true, joinedOnScreenCode: true }
  const expected = expectedPagespecName(screen)
  const exists = expected !== null && (corpus.pagespecs ?? []).some((p) => p.name === expected)
  return { name: expected, exists, joinedOnScreenCode: false }
}

export interface ImpactContext {
  corpus: ScopeCorpus
  kind: ChangeKind
  op: ChangeOp
  target: ChangeTarget
  sectionFolder?: string
  allocation: Allocation | null
  resolved?: ExistingMatch
  /** The duplicate report — actor / permission / screen preconditions read it. */
  existing?: ExistingReport
  /** The upstream-trace report — attribute / entity preconditions read it. */
  trace?: TraceReport
  /** Owner doc, relative to baRoot. */
  ownerFile: string
}

/** The SmartComponent types a screen heading may carry. */
export const SCREEN_TYPES = ['SmartListView', 'SmartForm', 'SmartDashboard', 'SmartKanban', 'SmartCard', 'SmartAppHome', 'SmartModuleHome', 'SmartSectionHome'] as const

/** The create-screen level file of a screen type. */
export function levelFileOf(screenType: string): string {
  switch (screenType) {
    case 'SmartListView':
    case 'SmartCard':
      return 'levels/list-screens.md'
    case 'SmartForm':
      return 'levels/form-screens.md'
    case 'SmartDashboard':
      return 'levels/dashboard-screens.md'
    case 'SmartKanban':
      return 'levels/kanban-screens.md'
    default:
      return 'levels/home-screens.md'
  }
}

const auditSpec = (c: ScopeCorpus, dimensions: string[]): Record<string, unknown> => ({
  baRoot: '<baRoot>',
  projectRoot: '.',
  scope: { app: c.scope.app, module: c.scope.module },
  dimensions,
})

const codeOf = (ctx: ImpactContext): string => ctx.allocation?.next ?? ctx.resolved?.code ?? ctx.target.code ?? '<code>'

function auditStep(step: number, ctx: ImpactContext, dimensions: string[]): ImpactStep {
  const { corpus } = ctx
  return {
    step,
    phase: 'audit',
    title: `Audit the ${dimensions.join(', ')} dimension(s) of ${corpus.scope.app}/${corpus.scope.module}${corpus.state.pagespecsPresent ? ' + /ba-audit-prd' : ''}`,
    cli: { cliPath: CLI_PATHS.auditBa, spec: auditSpec(corpus, dimensions), writes: true },
    why: 'The audits are the verdict — a step above that was skipped shows up here as an err with its remedy.',
    gateRules: [],
    status: 'required',
    data: {
      writesOnly: '_audit/*.md verdicts',
      ...(corpus.state.pagespecsPresent
        ? { alsoRun: '/ba-audit-prd (conversational — no CLI) on the module, dev-ready score ≥ 80' }
        : { note: 'No pagespecs/ — /ba-audit-prd has nothing to read yet.' }),
    },
  }
}

function handoffStep(step: number, ctx: ImpactContext, reentries: string[]): ImpactStep {
  const { corpus } = ctx
  const developed = corpus.state.developed
  return {
    step,
    phase: 'handoff',
    title: `Hand off to /ba-develop ${corpus.scope.app}/${corpus.scope.module} (no --force)`,
    skill: '/ba-develop',
    why: 'Phases 0-2 re-enter on a pre-entry coverage ERR and add only what is missing; Phase 3 regenerates the pagespec delta (compute-page-diff); Phase 4 always re-runs.',
    gateRules: [],
    status: developed ? 'required' : 'skipped',
    ...(developed ? {} : { skipReason: 'not developed yet (no .run-snapshot.json / core-seed state) — nothing to re-enter; run /ba-develop when the module is ready.' }),
    data: { reentries, force: false },
  }
}

// ---------------------------------------------------------------------------
// use-case
// ---------------------------------------------------------------------------

function useCaseImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target } = ctx
  const code = codeOf(ctx)
  const section = ctx.sectionFolder ?? '<section>'
  const sectionFile = `${corpus.scope.app}/${corpus.scope.module}/${section}`
  const rulesFile = `${corpus.scope.app}/${corpus.scope.module}/règles-métier.md`
  const steps: ImpactStep[] = []
  let n = 1

  const appActors = corpus.actors.find((a) => a.app.toLowerCase() === corpus.scope.app.toLowerCase())
  const actorKnown = target.actor
    ? (appActors?.actors ?? []).some(
        (a) => a.code.toLowerCase() === target.actor!.toLowerCase() || a.label.toLowerCase() === target.actor!.toLowerCase(),
      )
    : undefined
  steps.push({
    step: n++,
    phase: 'precondition',
    title: 'The primary actor exists in acteur.md',
    file: `${corpus.scope.app}/acteur.md`,
    why: 'A UC cannot cite an actor that does not exist — never SCREAMING_SNAKE a label into a fake code (create-use-case Actors gate).',
    gateRules: ['UC-008'],
    status: actorKnown === true ? 'skipped' : actorKnown === false ? 'required' : 'conditional',
    ...(actorKnown === true
      ? { skipReason: `actor "${target.actor}" resolved in ${corpus.scope.app}/acteur.md` }
      : actorKnown === false
        ? { condition: `actor "${target.actor}" is NOT in acteur.md — run /ba-change kind=actor first` }
        : { condition: 'name the primary actor; a new role → /ba-change kind=actor first' }),
    data: { actors: (appActors?.actors ?? []).map((a) => `${a.code} (${a.label})`) },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Write the UC block ${code}` : `Rewrite the UC block ${code} — never renumber an AC`,
    file: `${sectionFile}/use-case.md`,
    skill: 'ba-create-use-case',
    subWorkflow: 'Phase 2 (detail) — levels/detail.md, ONE UC',
    why:
      op === 'add'
        ? 'Level in the heading parenthetical, ≥ 1 AC, one AC per EXC-N — the AC contract feeds the Phase 4 [Fact]s.'
        : 'An AC renumbered or removed leaves a stale [Trait("AC",…)] behind — a green test on a deleted assertion (DEV-TEST-003). Add new ACs at the END; keep every existing id.',
    gateRules: op === 'add' ? ['UC-012', 'UC-022'] : ['UC-012', 'UC-022', 'DEV-TEST-003'],
    status: 'required',
    ...(corpus.state.sourcesPresent
      ? { data: { sources: 'registry present — cite `- **Sources** : SRC-NNN §n` (search via ' + CLI_PATHS.sourcesSearch + ')' } }
      : {}),
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: `Business rules for ${code} — link existing rules or author new ones`,
    file: rulesFile,
    skill: 'ba-create-business-rules',
    subWorkflow: 'Single-UC entry point',
    why: 'Every use case must be covered by ≥ 1 rule — a UC without rules cannot be vibecoded (no invariants, no validation, no failure paths).',
    gateRules: ['BR-007', 'BR-006'],
    status: 'required',
    data: { rulesInModule: corpus.rules.length },
  })

  const rbacRows = corpus.rbac.rows
  const actorRows = target.actor
    ? rbacRows.filter((r) => r.actorCode.toLowerCase() === target.actor!.toLowerCase() || (r.actorLabel ?? '').toLowerCase() === target.actor!.toLowerCase())
    : []
  steps.push({
    step: n++,
    phase: 'check',
    title: 'The actor holds ≥ 1 permission row in rbac.md; a new business action needs its own row',
    file: `${corpus.scope.app}/${corpus.scope.module}/rbac.md`,
    skill: 'ba-create-rbac',
    why: 'An actor that performs use cases but holds no permission cannot be authorised to do anything.',
    gateRules: ['XD-004', 'RBAC-004', 'RBAC-005'],
    status: !target.actor ? 'conditional' : actorRows.length > 0 ? 'conditional' : 'required',
    condition: !target.actor
      ? 'name the actor first — then: ≥ 1 row in rbac.md, plus a row for any new action the UC introduces → /ba-change kind=permission'
      : actorRows.length > 0
        ? `actor holds ${actorRows.length} row(s) — add a row only if the UC introduces a new action (approve, export, …) → /ba-change kind=permission`
        : 'no row found for the actor — author the access+read floor grants and the action the UC needs → /ba-change kind=permission',
    data: { actorRows: actorRows.map((r) => `${r.path} (${r.portee})`) },
  })

  const sectionScreens = corpus.screens.filter(
    (s) => s.section.toLowerCase() === (ctx.sectionFolder ?? '').toLowerCase() && (!target.entity || s.entity === target.entity),
  )
  steps.push({
    step: n++,
    phase: 'author',
    title: `A surface serves ${code}: an existing screen gains it in \`- **Cas d'usage liés**\` or an action line \`UC: ${code}\`, else a new screen`,
    file: `${sectionFile}/screen.md`,
    skill: 'ba-create-screen',
    subWorkflow: '§ Custom actions (create-screen/SKILL.md) or /ba-change kind=screen',
    why: 'A user-goal UC served by no screen, no custom action and no scheduled runtime is a phantom: green everywhere, failing [Fact]s later with nothing to point at.',
    gateRules: ['SCR-024', 'SCR-005'],
    status: 'required',
    data: {
      candidates: sectionScreens.map((s) => ({ code: s.code, type: s.screenType, entity: s.entity ?? null, pagespec: pagespecFor(corpus, s).name })),
      exemptWhen: 'level subfunction/summary, or the UC is `scheduled` (no actor)',
    },
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'Data-model trace: every entity / attribute the UC names exists in entité.md',
    file: `${corpus.scope.app}/${corpus.scope.module}/entité.md`,
    skill: 'ba-create-data-model',
    subWorkflow: 'Step 0 — trace audit (the UC IS the upstream trace)',
    why: 'A flow that names a field the model does not carry is dead prose; a new FK changes the lookup grants.',
    gateRules: ['DM-011', 'DM-025', 'RBAC-008'],
    status: 'conditional',
    condition: 'if the UC names an attribute or entity absent from entité.md → enrich the model, then run the MANDATORY post-step below',
    cli: {
      cliPath: CLI_PATHS.deriveLookupGrants,
      spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'derive' },
      writes: true,
    },
    data: { entities: corpus.entities?.entities.map((e) => `${e.code} ${e.name}`) ?? [], runCliOnlyIf: 'entité.md was written' },
  })

  const pagespecTargets = sectionScreens.map((s) => pagespecFor(corpus, s)).filter((p) => p.name !== null)
  steps.push({
    step: n++,
    phase: 'prd',
    title: `Pagespec delta: \`linkedUseCases[]\` += ${code} (and an \`actions[]\` entry with \`ucReference\` for a custom action) — inside the fenced json block ONLY`,
    file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/<Entity>.<view>.md`,
    skill: 'ba-create-prd',
    subWorkflow: '§ Single-pagespec entry point (edit the machine block; never touch uiDesign / lifecycle / other keys)',
    why: 'PRD leg of UC coverage. NEVER re-run /ba-create-prd on a module that has pagespecs: it rewrites every pagespec and drops the uiDesign overlay + lifecycle block /ui-design wrote.',
    gateRules: ['PRD-131', 'PRD-097'],
    status: corpus.state.pagespecsPresent ? 'required' : 'skipped',
    ...(corpus.state.pagespecsPresent ? {} : { skipReason: 'no pagespecs/ — the module has no PRD yet; /ba-create-prd is legitimate here (nothing to lose).' }),
    data: { pagespecs: pagespecTargets, prdApi: 'prd.api.md gains the handler bullet of a `kind: api` action' },
  })

  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Backfill the pagespec `linkedBusinessRules[]` from the rules authored above',
    cli: {
      cliPath: CLI_PATHS.deriveRuleLinks,
      spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'backfill' },
      writes: true,
    },
    why: 'THE field DEV-API-008 reads — a rule linked nowhere ships unenforced with the gate green. `needs-judgment` = author the link by hand, never an invented one.',
    gateRules: ['PRD-129', 'PRD-130'],
    status: corpus.state.pagespecsPresent ? 'required' : 'skipped',
    ...(corpus.state.pagespecsPresent ? {} : { skipReason: 'no pagespecs/ yet.' }),
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: `Prove the coverage: ${code} is \`covered\` on the BA leg (and the PRD leg when pagespecs exist)`,
    cli: { cliPath: CLI_PATHS.deriveUcCoverage, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module }, writes: false },
    why: 'Proof, not prose — the engine of SCR-024 / PRD-131 / UC-022.',
    gateRules: ['SCR-024', 'PRD-131', 'UC-022'],
    status: 'required',
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'If a rule authored above is workflow / state-transition: the form lifecycle still parses',
    cli: {
      cliPath: CLI_PATHS.deriveLifecycle,
      spec: { moduleRoot: `<baRoot>/${corpus.scope.app}/${corpus.scope.module}`, pagespecDir: `<baRoot>/${corpus.scope.app}/${corpus.scope.module}/pagespecs`, mode: 'check' },
      writes: false,
    },
    why: 'A new transition changes which fields a phase owns.',
    gateRules: ['PRD-120', 'PRD-121', 'XD-007'],
    status: corpus.state.pagespecsPresent ? 'conditional' : 'skipped',
    ...(corpus.state.pagespecsPresent ? { condition: 'a rule of type workflow or state-transition was authored' } : { skipReason: 'no pagespecs/ yet.' }),
  })

  steps.push(auditStep(n++, ctx, ['use-cases', 'rules', 'rbac', 'screens', 'cross-dimension']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 2a — DEV-API-009 (UC actions) / DEV-API-010 (custom action coverage) when an action was added',
      'Phase 2b — DEV-API-012 when the action lives on a screen controller',
      'Phase 3 — the modified pagespec lands in compute-page-diff.toRegenerate',
      'Phase 4 — always: one [Fact] per new AC (DEV-TEST-001/008)',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// business-rule
// ---------------------------------------------------------------------------

function ruleImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target } = ctx
  const code = codeOf(ctx)
  const ruleType = (target.ruleType ?? '').toLowerCase()
  const steps: ImpactStep[] = []
  let n = 1

  const wantedUcs = (target.useCase ?? '')
    .split(/[,\s]+/)
    .map((s) => s.trim())
    .filter(Boolean)
  const knownUcs = new Set(corpus.useCaseDocs.flatMap((d) => d.parsed.ucs.map((u) => u.ucCode.toLowerCase())))
  const missingUcs = wantedUcs.filter((u) => !knownUcs.has(u.toLowerCase()))
  steps.push({
    step: n++,
    phase: 'precondition',
    title: 'Every linked use case (`Cas d\'usage liés`) exists in the module',
    why: 'Never fabricate a reference (create-business-rules prohibition 3). No BA audit rule checks that a cited UC resolves (BR-005 is retired, BR-006 covers only rule → ≥ 1 UC) — this CLI carries the check.',
    gateRules: ['BR-006'],
    status: missingUcs.length > 0 ? 'required' : wantedUcs.length > 0 ? 'skipped' : 'conditional',
    ...(missingUcs.length > 0
      ? { condition: `unknown UC code(s): ${missingUcs.join(', ')} — run /ba-change kind=use-case first` }
      : wantedUcs.length > 0
        ? { skipReason: `${wantedUcs.length} linked UC(s) resolved` }
        : { condition: 'name the UC(s) the rule governs (a rule with no UC is BABOK-legal but unenforceable — see BR-006)' }),
    data: { linkedUcs: wantedUcs, knownUcs: knownUcs.size },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Write the rule ${code}` : `Rewrite the rule ${code}`,
    file: ctx.ownerFile,
    skill: 'ba-create-business-rules',
    subWorkflow: 'Single-UC entry point (Level 2 fields: Type, Sévérité, Portée, Condition, Expression, Code d\'erreur, ≥ 1 valid AND ≥ 1 invalid example, Cas d\'usage liés)',
    why: 'Rules feed FluentValidation + form errors + the BR-tagged tests; a rule without both examples stays a Level 1 draft.',
    gateRules: ['BR-002', 'BR-003', 'BR-004', 'BR-008', 'BR-010', 'BR-011'],
    status: 'required',
    ...(corpus.state.sourcesPresent
      ? { data: { sources: 'registry present — cite `- **Sources** : SRC-NNN §n` (search via ' + CLI_PATHS.sourcesSearch + ')' } }
      : {}),
  })

  const isFlow = ruleType === 'workflow' || ruleType === 'state-transition'
  const isAccess = ruleType === 'access' || ruleType === 'ownership'
  const isNumbering = ruleType === 'numbering'
  steps.push({
    step: n++,
    phase: 'check',
    title: 'Type-specific consequences: Flow lines ⇢ status enum; access ⇢ RBAC matrix; numbering ⇢ Code pattern',
    file: `${corpus.scope.app}/${corpus.scope.module}/entité.md`,
    why: 'A workflow rule names statuses that must exist in the entity enum (else /ba-change kind=attribute); an access rule is exempt from the PRD link but the MATRIX must carry it (/ba-change kind=permission); a numbering rule is the SPEC of the entity `**Code pattern**` (never a hand-rolled allocator).',
    gateRules: isFlow ? ['XD-001', 'XD-002', 'XD-003', 'DM-026'] : isAccess ? ['RBAC-001'] : isNumbering ? ['DM-017', 'PRD-132'] : ['XD-001', 'DM-026', 'DM-017'],
    status: ruleType ? 'required' : 'conditional',
    condition: ruleType
      ? undefined
      : 'depends on the rule type: workflow/state-transition → Flow + enum; access → permission row; numbering → Code pattern',
    ...(isNumbering
      ? { cli: { cliPath: CLI_PATHS.deriveCodeSpecs, spec: { moduleRoot: `<baRoot>/${corpus.scope.app}/${corpus.scope.module}`, mode: 'check' }, writes: false } }
      : {}),
    data: {
      ruleType: ruleType || null,
      stateAttributes: (corpus.entities?.entities ?? []).flatMap((e) =>
        e.attributes.filter((a) => /\//.test(a.constraints)).map((a) => `${e.name}.${a.name}: ${a.constraints}`),
      ),
    },
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'Every attribute the `Expression` names exists in entité.md',
    file: `${corpus.scope.app}/${corpus.scope.module}/entité.md`,
    skill: 'ba-create-data-model',
    why: 'A rule on a column that does not exist is dead code — the scaffolded validator has nothing to read.',
    gateRules: ['DM-025'],
    status: 'conditional',
    condition: 'compare the Expression identifiers with the entity attributes; a missing one → /ba-change kind=attribute (the rule IS its upstream trace)',
    data: { entities: corpus.entities?.entities.map((e) => `${e.name}: ${e.attributes.map((a) => a.name).join(', ')}`) ?? [] },
  })

  steps.push({
    step: n++,
    phase: 'prd',
    title: `Link ${code} to its pagespec(s): derive-rule-links backfill; \`needs-judgment\` → author \`linkedBusinessRules[]\` by hand (json block only)`,
    file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/<Entity>.<view>.md`,
    cli: {
      cliPath: CLI_PATHS.deriveRuleLinks,
      spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'backfill' },
      writes: true,
    },
    why: 'THE field DEV-API-008 reads — the audit\'s main BR silent-loss point. Mapping ladder: rule-doc folder → linked-UC sections → needs-judgment. Optional: an action line gains `BR: ' + code + '`. NEVER /ba-create-prd on a module with pagespecs.',
    gateRules: ['PRD-129', 'PRD-130'],
    status: isAccess ? 'skipped' : corpus.state.pagespecsPresent ? 'required' : 'skipped',
    ...(isAccess
      ? { skipReason: 'access/ownership rules are exempt from the PRD link (their channel is the RBAC matrix).' }
      : corpus.state.pagespecsPresent
        ? {}
        : { skipReason: 'no pagespecs/ — the module has no PRD yet; /ba-create-prd is legitimate here.' }),
  })

  steps.push(auditStep(n++, ctx, ['rules', 'use-cases', 'cross-dimension']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 2a pre-entry checks do NOT see a new rule (DEV-API-024/010/026 only) — the post-phase audit-dev-api DEV-API-008 (module-scoped trace) and audit-dev-tests DEV-TEST-009 catch it in the auto-heal loop: business layer re-scaffolded from linkedBusinessRules[]',
      'Phase 4 — a [Trait("BR","' + code + '")] test under Tests/<Module>/',
      'run /audit-fix after the run for anything left',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// actor
// ---------------------------------------------------------------------------

/** Seed-parity check — Phase 0's own engine, run here as proof before the hand-off. */
function seedParityStep(step: number, ctx: ImpactContext, why: string): ImpactStep {
  const { corpus } = ctx
  return {
    step,
    phase: 'check',
    title: 'Seed parity: rbac.md + acteur.md ⇄ the seeded state (the DEV-CORE-011 engine)',
    cli: {
      cliPath: CLI_PATHS.deriveRbacGrants,
      spec: { baRoot: '<baRoot>', apps: [corpus.scope.app], mode: 'check', projectPath: '<projectPath>' },
      writes: false,
    },
    why,
    gateRules: ['DEV-CORE-011'],
    status: corpus.state.developed ? 'required' : 'skipped',
    ...(corpus.state.developed ? {} : { skipReason: 'not developed yet — no seed state to compare (spec.projectPath locates .smartstack/core-seed/*.state.json).' }),
  }
}

function actorImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target, existing } = ctx
  const code = codeOf(ctx)
  const label = target.title ?? existing?.resolved?.title ?? '<label>'
  const steps: ImpactStep[] = []
  let n = 1
  const ownFile = `${corpus.scope.app}/acteur.md`
  const sameActor = existing?.exact ?? []

  steps.push({
    step: n++,
    phase: 'precondition',
    title: 'The label is not already an actor of ANY application, and its seeded role code is unique',
    file: ownFile,
    why: 'Actors are project-scoped: one label = one actor = one seeded role (`slugifyRoleCode(label)`, lib/ba-actors). An actor that exists elsewhere gets a `Périmètre` line here, never a second code — two actors with the same role code collide at seed time (`role-code-collision`).',
    gateRules: ['ACT-002', 'ACT-006'],
    status: sameActor.length > 0 ? 'required' : target.title ? 'skipped' : 'conditional',
    ...(sameActor.length > 0
      ? {
          condition: sameActor.some((m) => m.file.toLowerCase() === ownFile.toLowerCase())
            ? `same actor already in THIS application: ${sameActor.map((m) => `${m.code} (${m.reason})`).join(', ')} — this is an op=modify of that actor, never a second code (ACT-002)`
            : `same actor found in another application: ${sameActor.map((m) => `${m.code} (${m.file}, ${m.reason})`).join(', ')} — REUSE it: write its block in ${ownFile} with the SAME code and a \`- **Périmètre**\` line for this application, never a new code`,
        }
      : target.title
        ? { skipReason: `no actor labelled « ${target.title} » (nor the same role code) in ${corpus.actors.length} application(s)` }
        : { condition: 'name the actor label first — the check runs on it' }),
    data: { actorsByApp: corpus.actors.map((a) => ({ app: a.app, actors: a.actors.map((x) => `${x.code} ${x.label}`) })) },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Write the actor block ${code} — « ${label} »` : `Rewrite the actor block ${code}`,
    file: ownFile,
    skill: 'ba-create-actors',
    subWorkflow: '§ Actor fields (Type, Description, Origine required; Catégorie per _workflow/role-taxonomy.md; Périmètre)',
    why: 'The seeded role is derived from THIS block: role.code = slugifyRoleCode(label), role.name = label, RoleCategory from Catégorie (absent → Custom, `Global` refused).',
    gateRules: ['ACT-001', 'ACT-002'],
    status: 'required',
    ...(corpus.state.sourcesPresent
      ? { data: { sources: 'registry present — cite `- **Sources** : SRC-NNN §n` (search via ' + CLI_PATHS.sourcesSearch + ')' } }
      : {}),
  })

  const ucCount = corpus.useCaseDocs.reduce((s, d) => s + d.parsed.ucs.length, 0)
  steps.push({
    step: n++,
    phase: 'author',
    title: 'The use cases this actor drives — new ones, or existing UCs whose `Acteur principal` / `Acteurs secondaires` change',
    file: `${corpus.scope.app}/${corpus.scope.module}/<section>/use-case.md`,
    skill: 'ba-create-use-case',
    subWorkflow: '/ba-change kind=use-case per new UC; op=modify on an existing UC for an actor change',
    why: 'An actor no use case names is decorative — and a UC citing a code absent from acteur.md is an err.',
    gateRules: ['UC-008', 'ACT-006'],
    status: 'required',
    condition: undefined,
    data: { useCasesInModule: ucCount, sections: corpus.sectionFolders },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: 'RBAC rows in every module the actor acts in — the access + read floor per section, then the actions it needs',
    file: `${corpus.scope.app}/${corpus.scope.module}/rbac.md`,
    skill: 'ba-create-rbac',
    subWorkflow: '/ba-change kind=permission, one row at a time (this module first; other modules of the Périmètre next)',
    why: 'An actor with no permission in a module cannot be authorised to do anything there (the floor exists by construction, the GRANT is the human row).',
    gateRules: ['RBAC-002', 'RBAC-004', 'RBAC-005'],
    status: 'required',
    data: { sectionsOfThisModule: corpus.sectionFolders, rowsInThisModule: corpus.rbac.rows.length },
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'Portée `les siennes` / `équipe` / `custom` on its rows → the data scope must be materialised',
    file: `${corpus.scope.app}/${corpus.scope.module}/rbac.md`,
    why: '`own` needs the entity to be owned (DataScopePolicy + IOwnedEntity); `team`/`custom` are declared expectations, not runtime restrictions until the HR application materialises them.',
    gateRules: ['RBAC-006', 'RBAC-010'],
    status: 'conditional',
    condition: 'only when a row of the new actor carries a Portée other than `toutes`',
  })

  if (op === 'modify') {
    steps.push({
      step: n++,
      phase: 'check',
      title: 'A renamed label changes the seeded role code — a prod rename travels through derive-seed-delta',
      why: 'role.code = slugifyRoleCode(label): the boot seed is additive and would create a SECOND role; the rename reaches prod only through the release-branch delta script (gitflow PR gate) — announce it, never run it here (red lane).',
      gateRules: ['DEV-CORE-011'],
      status: 'conditional',
      condition: 'only when the label (not just Description/Périmètre) changes',
      data: { deltaCli: 'development/backend/core-seed/cli/derive-seed-delta — release branch only, user decision' },
    })
  }

  steps.push({
    step: n++,
    phase: 'prd',
    title: 'No pagespec delta for an actor',
    why: 'Pagespecs carry permission PATHS, never actors — the row of step 4 is what reaches them.',
    gateRules: [],
    status: 'skipped',
    skipReason: 'permissions are paths, not actors.',
  })

  steps.push(seedParityStep(n++, ctx, 'The new role and its mappings must reach the seed: `unmatchedActors` / `missingGrants` non-empty = Phase 0 re-entry.'))
  steps.push({
    ...auditStep(n++, ctx, ['actors', 'rbac', 'use-cases']),
    data: { note: 'the actors dimension is PROJECT-scoped (every <APP>/acteur.md) — the module scope only narrows rbac/use-cases.' },
  })
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 0 — scaffold-core-seed re-run (additive): the role + its RolePermissions from the derive-rbac-grants fragment (DEV-CORE-011)',
      'no Phase 3 — an actor changes no page',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// permission
// ---------------------------------------------------------------------------

function permissionImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target, existing } = ctx
  const steps: ImpactStep[] = []
  let n = 1
  const file = `${corpus.scope.app}/${corpus.scope.module}/rbac.md`
  const appLower = corpus.scope.app.toLowerCase()
  const path = target.permissionPath?.trim()
  const parsed = path ? parsePermissionPath(`${appLower}.${path}`) : null
  const portee = canonicalPortee(target.portee)
  const appActors = corpus.actors.find((a) => a.app.toLowerCase() === appLower)?.actors ?? []
  const actorKnown = target.actor
    ? appActors.some((a) => a.code.toLowerCase() === target.actor!.toLowerCase() || a.label.toLowerCase() === target.actor!.toLowerCase())
    : undefined
  const allGiven = target.actor !== undefined && parsed !== null && portee !== null
  const floorActions = parsed ? FLOOR_BY_GRAIN[parsed.grain] : []
  const inFloor = parsed ? floorActions.includes(parsed.action) : false

  steps.push({
    step: n++,
    phase: 'precondition',
    title: 'The actor exists, the path parses (`module.section[.resource].action`, no app prefix), the action is in the vocabulary, the Portée is canonical, the tuple is absent',
    file,
    why: 'A row citing an unknown actor is an err (RBAC-005); the 12 actions + the `read.all` tier are the closed vocabulary (lib/permission-actions); the Portée vocabulary is closed (RBAC-007); the app prefix is added at the page/controller boundary, never in a human row (create-rbac prohibition 10).',
    gateRules: ['RBAC-005', 'RBAC-007'],
    status: allGiven && actorKnown ? 'skipped' : 'conditional',
    ...(allGiven && actorKnown
      ? { skipReason: `actor, path (${parsed!.grain} grain, node \`${parsed!.nodePath.slice(appLower.length + 1)}\`) and Portée \`${portee}\` all resolve` }
      : { condition: 'name the actor (code or label), the path and the Portée — the CLI blocks on an unknown one' }),
    data: {
      actors: appActors.map((a) => `${a.code} (${a.label})`),
      actions: [...PERMISSION_ACTIONS, 'read.all'],
      portees: ['toutes|all', 'les siennes|own', 'attribuées|assigned', 'équipe|team', 'personnalisée|custom (+ filter clause)'],
      ...(parsed ? { grain: parsed.grain, action: parsed.action, inFloor } : {}),
    },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? 'Append the human row to the matrix — the two machine blocks untouched' : 'Rewrite the human row — the two machine blocks untouched',
    file,
    skill: 'ba-create-rbac',
    subWorkflow: 'decision row « add/modify a permission » — `| BA-… (Label) | `module.section.action` | portée |`',
    why: inFloor
      ? `\`${parsed!.action}\` is part of the permission FLOOR of a ${parsed!.grain} node — the floor is seeded by construction, but the GRANT to this actor is the human row.`
      : 'The human rows carry the grants and the extra actions (approve, export, `.read.all`…); the `ba:rbac-floor` and `ba:rbac-derived-lookups` blocks are machine-owned.',
    gateRules: ['RBAC-001'],
    status: 'required',
    data: { floorOfGrain: floorActions, existingTupleOrSibling: [...(existing?.exact ?? []), ...(existing?.similar ?? [])].map((m) => m.title ?? '') },
  })

  const nodeRows = parsed
    ? corpus.rbac.rows.filter(
        (r) =>
          (r.actorCode.toLowerCase() === (target.actor ?? '').toLowerCase() || (r.actorLabel ?? '').toLowerCase() === (target.actor ?? '').toLowerCase()) &&
          r.path.toLowerCase().startsWith(parsed.nodePath.slice(appLower.length + 1).toLowerCase() + '.'),
      )
    : []
  // The action of a human row — `read.all` is ONE action (the scope tier), not `all`.
  const actionOfRow = (path: string): string => {
    const p = path.toLowerCase()
    return p.endsWith('.read.all') ? 'read.all' : (p.split('.').pop() ?? '')
  }
  const nodeActions = new Set(nodeRows.map((r) => actionOfRow(r.path)))
  steps.push({
    step: n++,
    phase: 'check',
    title: 'The same actor holds `access` + `read` on that node; no segregation-of-duties pair (create + approve, submit + approve, delete + restore)',
    file,
    why: 'A grant on a node the actor cannot reach is dead; an actor who both creates and approves the same object defeats the control.',
    gateRules: ['RBAC-002', 'RBAC-003'],
    status: parsed ? 'required' : 'conditional',
    ...(parsed ? {} : { condition: 'once the path is known' }),
    data: {
      actorActionsOnNode: [...nodeActions].sort(),
      hasAccess: nodeActions.has('access'),
      hasRead: nodeActions.has('read') || nodeActions.has('read.all'),
      note: 'access/read may also come from the FLOOR (seeded for every node) — the audit reads the human rows; write them when the actor must reach the node.',
    },
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'If the row gates a custom action: the screen action line and the pagespec `actions[].permission` name it, at the own `module.section` grain',
    file: `${corpus.scope.app}/${corpus.scope.module}/<section>/screen.md`,
    skill: 'ba-create-screen',
    subWorkflow: '§ Custom actions — `permission:` on the action line; pagespec `actions[].permission`',
    why: 'derive-action-specs rejects an action whose permission does not root at its own module.section (PRD-128).',
    gateRules: ['PRD-128'],
    status: 'conditional',
    condition: 'only when the action is a business verb (approve, export, assign…) served by a screen action',
  })

  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Derived lookup grants still fresh (a `read`/`lookup` grant may make a derived row redundant)',
    cli: { cliPath: CLI_PATHS.deriveLookupGrants, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'check' }, writes: false },
    why: 'The machine block suppresses a derived lookup when the actor already holds read on the producer — re-derive (`mode: derive`) when the check reports drift.',
    gateRules: ['RBAC-008'],
    status: 'required',
  })
  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Permission-floor mirror still fresh',
    cli: { cliPath: CLI_PATHS.derivePermissionFloor, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'check' }, writes: false },
    why: 'The `ba:rbac-floor` mirror lists the node paths the human rows may reference — drift there breaks the human review, never the seed.',
    gateRules: ['RBAC-009'],
    status: 'required',
  })

  if (op === 'modify') {
    steps.push({
      step: n++,
      phase: 'check',
      title: 'A narrowed Portée or a revoked grant does not reach an existing database through the boot seed',
      why: 'The boot seed is strictly additive (insert-if-not-exists): a revoked RolePermission or a changed scope tier travels ONLY through the release-branch derive-seed-delta script (gitflow PR gate). Announce it; never run it here (red lane). `derive-rbac-grants --mode check` reports the revoked mapping as `extraGrants`.',
      gateRules: ['DEV-CORE-011', 'RBAC-006', 'RBAC-010'],
      status: 'conditional',
      condition: 'only when the change removes or narrows what the actor could do',
    })
  }

  steps.push(seedParityStep(n++, ctx, 'The new grant must reach the seed: `missingGrants` non-empty = Phase 0 re-entry (seeds are additive at boot).'))
  steps.push(auditStep(n++, ctx, ['rbac', 'cross-dimension']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 0 — scaffold-core-seed re-run (additive): the RolePermission mapping from the derive-rbac-grants fragment (DEV-CORE-011)',
      'Phase 2 — DEV-API-021 (permission constants ⊆ seeded grants) / DEV-API-033 ([RequirePermission] guard) when the row backs a NEW action endpoint',
      'no Phase 3 unless a screen action was added',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// attribute
// ---------------------------------------------------------------------------

function traceStep(step: number, ctx: ImpactContext, subject: string, gateRules: string[]): ImpactStep {
  const { corpus, trace, op } = ctx
  const found = trace?.found ?? false
  // On modify the item already exists: its trace is DM-011 / DM-025's business, never a gate here.
  const status: ImpactStep['status'] = found ? 'skipped' : op === 'modify' ? (trace ? 'conditional' : 'skipped') : 'required'
  return {
    step,
    phase: 'precondition',
    title: `Upstream trace: ${subject} is named by a use case or a business rule of THIS module`,
    file: `${corpus.scope.app}/${corpus.scope.module}/<section>/use-case.md · règles-métier.md`,
    why: 'The set of entity sources is CLOSED (create-data-model prohibition 1): a column nobody upstream asks for is a hallucination the audits err on. The search is lexical (whole word, accents folded, every form of the name) — a synonym it cannot see blocks wrongly, and the answer is then the missing UC / rule, which is the door the phase wants anyway.',
    gateRules,
    status,
    ...(found
      ? { skipReason: `${trace!.hits.length} hit(s) — first: ${trace!.hits[0]!.file}:${trace!.hits[0]!.line} « ${trace!.hits[0]!.excerpt.slice(0, 90)} »` }
      : op === 'modify'
        ? trace
          ? { condition: 'the existing item is not named upstream — a rename should re-trace it, else DM-025 / DM-011 will flag it; not a gate for a modification' }
          : { skipReason: 'op=modify — the item exists; its upstream trace is audited by DM-011 / DM-025, not gated here' }
        : { condition: 'no upstream mention found — write the use case or the rule that needs it first (/ba-change kind=use-case | kind=business-rule)' }),
    data: { hits: (trace?.hits ?? []).slice(0, 5), docsScanned: trace?.docsScanned ?? 0 },
  }
}

function attributeImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target, existing } = ctx
  const entityName = target.entity ?? '<Entity>'
  const attr = target.attribute ?? existing?.resolved?.title?.split('.')[1]?.split(' ')[0] ?? '<Attribute>'
  const entity = (corpus.entities?.entities ?? []).find((e) => e.name.toLowerCase() === entityName.toLowerCase())
  const file = `${corpus.scope.app}/${corpus.scope.module}/entité.md`
  const type = (target.attributeType ?? '').toLowerCase()
  const isFk = /id$/i.test(attr) && attr.toLowerCase() !== 'id' && (type === '' || /guid/.test(type))
  const isEnum = type === 'enum' || /\//.test(type)
  const steps: ImpactStep[] = []
  let n = 1

  steps.push(traceStep(n++, ctx, `« ${attr} »`, ['DM-025', 'DM-011']))

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Add the row \`| ${attr} | <type> | <contraintes> | <calculé> |\` to ${entityName}'s attribute table + its Traçabilité` : `Rewrite the row of ${entityName}.${attr}`,
    file,
    skill: 'ba-create-data-model',
    subWorkflow: 'Step 0 trace → levels/attributes.md (type vocabulary, constraints, Calculé) — splice the ONE entity block, every other block verbatim',
    why: 'The row is what scaffold-entity turns into the column, the DTOs and the EF configuration; the Traçabilité line is what DM-025 / DM-011 read.',
    gateRules: ['DM-002', 'DM-005', 'DM-007', 'DM-028'],
    status: 'required',
    data: { entity: entity ? `${entity.code} ${entity.name}` : null, attributes: entity?.attributes.map((a) => `${a.name}: ${a.type}`) ?? [] },
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'A foreign key (`XxxId` Guid) needs its `**Relations**` entry — then the MANDATORY lookup-grants post-step',
    file,
    skill: 'ba-create-data-model',
    subWorkflow: 'levels/relationships.md — `Entity *→1 Target — FK XxxId, scope same-module|cross-module (APP/MOD)|core, onDelete …`',
    cli: { cliPath: CLI_PATHS.deriveLookupGrants, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'derive' }, writes: true },
    why: 'A bare `*Id` Guid gets no FK constraint (DM-013); a new FK changes which producer sections the module\'s actors need as dropdowns — the machine block of rbac.md must follow (RBAC-008).',
    gateRules: ['DM-013', 'RBAC-008'],
    status: isFk ? 'required' : 'conditional',
    ...(isFk ? {} : { condition: `only if « ${attr} » is a foreign key (a \`…Id\` Guid) — then name the target entity; run the CLI only after entité.md was written` }),
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'A state enum needs its rule, its use case and its screen; a computed value is a formula, not a column; a frequently filtered column is an index',
    file,
    why: 'A status nothing moves is dead state (XD-001..003); a computed column stored is a DM-005 err; a list filtering on an unindexed column is the classic scan (DM-024); an index naming an unknown column is DM-023.',
    gateRules: isEnum ? ['XD-001', 'XD-002', 'XD-003', 'DM-026'] : ['DM-005', 'DM-024', 'DM-023'],
    status: isEnum ? 'required' : 'conditional',
    ...(isEnum ? {} : { condition: 'depends on the attribute: enum with state semantics → XD-001..003; computed → `Calculé` column; filtered → `**Index**`' }),
  })

  const entityScreens = corpus.appScreens.filter((s) => s.entity?.toLowerCase() === entityName.toLowerCase())
  steps.push({
    step: n++,
    phase: 'author',
    title: `Screens bound to ${entityName}: add « ${attr} » to \`Colonnes\` / \`Champs\` / \`Filtres\` where it belongs — within the budgets`,
    file: `${corpus.scope.app}/${corpus.scope.module}/<section>/screen.md`,
    skill: 'ba-create-screen',
    subWorkflow: 'levels/list-screens.md (≤ 7 default-visible columns, ≤ 3 primary filters) · levels/form-screens.md (Section / Onglet grouping)',
    why: 'A column the screens never show is a dead attribute for the user; a column added without judgment inflates the list past its budget.',
    gateRules: ['SCR-016', 'SCR-017', 'SCR-018', 'PRD-109', 'PRD-110'],
    status: entityScreens.length > 0 ? 'required' : 'skipped',
    ...(entityScreens.length > 0 ? {} : { skipReason: `no screen binds ${entityName} yet` }),
    data: { screens: entityScreens.map((s) => ({ code: s.code, type: s.screenType, section: s.section, pagespec: pagespecFor(corpus, s).name })) },
  })

  steps.push({
    step: n++,
    phase: 'prd',
    title: `Pagespec delta of every ${entityName} view: \`columns[]\` / \`fields[]\` / \`filters[]\` gain the attribute — json block only`,
    file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/${entityName}.<view>.md`,
    skill: 'ba-create-prd',
    subWorkflow: '§ Single-pagespec entry point — edit the machine block; a FK filter carries `fkTo` (derive-filter-fks), a phased field its `lifecycle` phase (derive-lifecycle --mode check), a sectioned form its `sections[]` (derive-form-sections), a summary field the `summary` band (derive-detail-summary --mode check)',
    cli: { cliPath: CLI_PATHS.deriveFilterFks, spec: { moduleRoot: `<baRoot>/${corpus.scope.app}/${corpus.scope.module}`, entity: entityName, mode: 'check' }, writes: false },
    why: 'The pagespec is what scaffold-component renders; a FK filter without `fkTo` is a free-text GUID box (PRD-113). Run the CLI in `mode: derive` (it WRITES) only when the check reports drift. Never /ba-create-prd on a module with pagespecs.',
    gateRules: ['PRD-113', 'PRD-111', 'PRD-120', 'PRD-134'],
    status: corpus.state.pagespecsPresent && entityScreens.length > 0 ? 'required' : 'skipped',
    ...(corpus.state.pagespecsPresent && entityScreens.length > 0 ? {} : { skipReason: corpus.state.pagespecsPresent ? `no screen binds ${entityName}` : 'no pagespecs/ — the module has no PRD yet; /ba-create-prd is legitimate here.' }),
    data: { alsoRun: [CLI_PATHS.deriveLifecycle + ' mode:check', CLI_PATHS.deriveDetailSummary + ' mode:check', CLI_PATHS.deriveFormSections + ' mode:check'] },
  })

  if (op === 'modify') {
    steps.push({
      step: n++,
      phase: 'check',
      title: 'A retyped or renamed column is a DESTRUCTIVE migration; changed enum values re-open the state graph',
      why: 'scaffold-entity regenerates the class (DEV-DOM-002) and /efcore renders the migration verdict — a narrowing or a drop is 🟡/🔴, the user\'s call, never run here; changed status values must still be reachable (DM-026) and the board / lifecycle read them (derive-kanban-spec, derive-lifecycle --mode check).',
      gateRules: ['DEV-DOM-002', 'DM-026', 'PRD-120', 'PRD-135'],
      status: 'conditional',
      condition: 'only when the type, the name or the enum values change (a constraint or a Calculé formula change is additive)',
    })
  }

  steps.push(auditStep(n++, ctx, ['data-model', 'screens', 'cross-dimension', 'cross-ref-code']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 1 — DEV-DOM-002 (the attribute is missing on the .cs) → scaffold-entity + EF migration through /efcore (an additive column is a 🟢 verdict); DEV-DAT-008/009 for a FK / an index',
      'Phase 2a/2b — the DTOs and endpoint shapes of the touched entity regenerate',
      'Phase 3 — every modified pagespec lands in compute-page-diff.toRegenerate',
      'Phase 4 — always',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// entity
// ---------------------------------------------------------------------------

function entityImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target } = ctx
  const code = codeOf(ctx)
  const name = target.entity ?? target.title ?? ctx.resolved?.title ?? '<Entity>'
  const file = `${corpus.scope.app}/${corpus.scope.module}/entité.md`
  const moduleRoot = `<baRoot>/${corpus.scope.app}/${corpus.scope.module}`
  const steps: ImpactStep[] = []
  let n = 1

  steps.push(traceStep(n++, ctx, `« ${name} »`, ['DM-011', 'DM-018', 'DM-019', 'CODE-001', 'CODE-006']))

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Write the entity block ${code} — ${name}` : `Rewrite the entity block ${code}`,
    file,
    skill: 'ba-create-data-model',
    subWorkflow: 'Step 0 trace → Step 1 (classification, Préfixe table, Portée, Traçabilité, attributes with Id PK, Relations, Index, Affichage, Personne when it is a person) — full re-Write, every other block verbatim',
    why: 'scaffold-entity, the EF configuration, the migration, the DTOs and the lookups all read this block; a person modelled without the auth_Users link is CODE-007.',
    gateRules: ['DM-001', 'DM-002', 'DM-005', 'DM-013', 'DM-023', 'DM-028'],
    status: 'required',
    data: { entitiesInModule: (corpus.entities?.entities ?? []).map((e) => `${e.code} ${e.name}`) },
  })

  steps.push({
    step: n++,
    phase: 'derive',
    title: 'MANDATORY post-step after EVERY entité.md Write: derive the lookup grants',
    cli: { cliPath: CLI_PATHS.deriveLookupGrants, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'derive' }, writes: true },
    why: 'The FKs you just authored decide which producer sections the module\'s actors need as dropdowns — rbac.md\'s machine block follows the data model (create-data-model § After writing).',
    gateRules: ['RBAC-008'],
    status: 'required',
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'Where does it live — a satellite of an existing section (rows at the section grain) or a NEW section?',
    file: `${corpus.scope.app}/${corpus.scope.module}/rbac.md`,
    skill: 'ba-create-rbac',
    subWorkflow: '/ba-change kind=permission for the section rows; a NEW section is /ba-create-menu\'s job (out of this change\'s scope), then /ba-loop on the module',
    why: 'An entity nobody can reach is dead (RBAC-002); a new menu node changes the nav seed and every code family.',
    gateRules: ['RBAC-002'],
    status: 'conditional',
    condition: `satellite of one of: ${corpus.sectionFolders.join(', ') || '(no section)'} — else a new section first`,
    data: { sections: corpus.sectionFolders },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: `Screens of ${name}: list / detail / form (/ba-change kind=screen, one at a time) — and the parent\'s related tab`,
    file: `${corpus.scope.app}/${corpus.scope.module}/<section>/screen.md`,
    skill: 'ba-create-screen',
    subWorkflow: 'levels/list-screens.md · levels/form-screens.md; the parent detail gains `- **Onglet lié « … »**` (derive-related-tabs suggests it)',
    cli: { cliPath: CLI_PATHS.deriveRelatedTabs, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, entity: '<Parent>', mode: 'derive' }, writes: false },
    why: 'A section with no screen (SCR-002) or a satellite with no tab on its parent (SCR-009/014) is invisible to the user; a user-goal UC on the entity needs its surface (SCR-024).',
    gateRules: ['SCR-002', 'SCR-009', 'SCR-014', 'SCR-024'],
    status: 'required',
  })

  const prdPresent = corpus.state.pagespecsPresent
  steps.push({
    step: n++,
    phase: 'prd',
    title: `New pagespecs \`${name}.list.md\` / \`.detail.md\` / \`.form.md\` — one per screen, through the Single-pagespec entry point; \`routeFamily\` + \`routeParent\` on a satellite`,
    file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/${name}.<view>.md`,
    skill: 'ba-create-prd',
    subWorkflow: '§ Single-pagespec entry point (ONE pagespec per call, siblings untouched, prd.md/slices not regenerated) + the `prd.entities.md` bullet',
    why: 'Every screen needs its pagespec (PRD-070); a satellite without `routeFamily`/`routeParent` mis-routes every 360 tab onto the porteur (PRD-108). Never /ba-create-prd on a module with pagespecs.',
    gateRules: ['PRD-070', 'PRD-103', 'PRD-104', 'PRD-105', 'PRD-108', 'PRD-114'],
    status: prdPresent ? 'required' : 'skipped',
    ...(prdPresent ? {} : { skipReason: 'no pagespecs/ — the module has no PRD yet; /ba-create-prd is legitimate here (nothing to lose).' }),
  })
  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Nav resources: every new (routeParent, routeFamily) pair resolves to ONE nav resource — collisions are blocking',
    cli: { cliPath: CLI_PATHS.deriveNavResources, spec: { moduleRoot }, writes: false },
    why: 'A registry componentKey whose node chain Phase 0 never seeded is unreachable (the 21-dead-keys incident, DEV-UI-046).',
    gateRules: ['DEV-UI-046'],
    status: prdPresent ? 'required' : 'skipped',
    ...(prdPresent ? {} : { skipReason: 'no pagespecs/ yet.' }),
  })
  steps.push({
    step: n++,
    phase: 'check',
    title: 'Declared related tabs valid on BOTH sides (screen.md + pagespecs)',
    cli: { cliPath: CLI_PATHS.deriveRelatedTabs, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'validate', pagespecs: true }, writes: false },
    why: 'RTV-001..009 on the screen side, PRD-103..105 + the tab-bar budget on the pagespec side.',
    gateRules: ['RTV-001', 'RTV-009', 'PRD-103', 'PRD-105', 'PRD-133'],
    status: prdPresent ? 'required' : 'conditional',
    ...(prdPresent ? {} : { condition: 'screen side only until the pagespecs exist (`pagespecs: false`)' }),
  })
  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Backfill the business-rule links of the new pagespecs, then prove the UC coverage',
    cli: { cliPath: CLI_PATHS.deriveRuleLinks, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'backfill' }, writes: true },
    why: 'THE field DEV-API-008 reads (PRD-129/130); then derive-uc-coverage must report every user-goal UC of the entity `covered` (SCR-024 / PRD-131).',
    gateRules: ['PRD-129', 'PRD-130', 'SCR-024', 'PRD-131'],
    status: prdPresent ? 'required' : 'skipped',
    ...(prdPresent ? {} : { skipReason: 'no pagespecs/ yet.' }),
    data: { then: CLI_PATHS.deriveUcCoverage },
  })

  steps.push(auditStep(n++, ctx, ['data-model', 'rules', 'rbac', 'screens', 'cross-dimension', 'cross-ref-code']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 0 — the nav resource + permission floor of a new satellite (additive seed, DEV-CORE-011)',
      'Phase 1 — DEV-DOM-001 (the entity has no .cs) → scaffold-entity + EF migration through /efcore (a new table is a 🟢 verdict)',
      'Phase 2a — DEV-API-024 (controller existence) / 2b — DEV-API-012 (screen endpoints)',
      'Phase 3 — the added pagespecs land in compute-page-diff.toRegenerate',
      'Phase 4 — always',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// screen
// ---------------------------------------------------------------------------

function screenImpact(ctx: ImpactContext): ImpactStep[] {
  const { corpus, op, target, existing } = ctx
  const code = codeOf(ctx)
  const section = ctx.sectionFolder ?? '<section>'
  const file = `${corpus.scope.app}/${corpus.scope.module}/${section}/screen.md`
  const moduleRoot = `<baRoot>/${corpus.scope.app}/${corpus.scope.module}`
  const pagespecDir = `${moduleRoot}/pagespecs`
  const screenType = target.screenType ?? '<SmartType>'
  const isForm = screenType === 'SmartForm'
  const folds = screenType === 'SmartKanban' || screenType === 'SmartCard'
  const entityKnown = target.entity ? (corpus.entities?.entities ?? []).some((e) => e.name.toLowerCase() === target.entity!.toLowerCase()) : undefined
  const floor = FLOOR_BY_GRAIN.section.map((a) => `${corpus.scope.module.toLowerCase()}.${section}.${a}`)
  const permission = target.permissionPath?.trim()
  const permKnown = permission
    ? corpus.rbac.rows.some((r) => r.path.toLowerCase() === permission.toLowerCase()) || floor.includes(permission.toLowerCase())
    : undefined
  const wantedUcs = (target.useCase ?? '').split(/[,\s]+/).map((s) => s.trim()).filter(Boolean)
  const knownUcs = new Set(corpus.useCaseDocs.flatMap((d) => d.parsed.ucs.map((u) => u.ucCode.toLowerCase())))
  const missingUcs = wantedUcs.filter((u) => !knownUcs.has(u.toLowerCase()))
  const sameSurface = (existing?.exact ?? []).filter((m) => m.reason === 'same-surface')
  const allResolved = entityKnown === true && permKnown === true && wantedUcs.length > 0 && missingUcs.length === 0 && sameSurface.length === 0
  const expected = folds ? null : expectedPagespecNameFor(screenType, target.entity, target.mode)
  const steps: ImpactStep[] = []
  let n = 1

  steps.push({
    step: n++,
    phase: 'precondition',
    title: 'The entity exists in entité.md, the permission is a human row or a floor path, every linked UC exists, and no screen already serves this surface',
    file,
    why: 'A screen bound to an unknown entity is XD-005/SCR-003; a permission nobody seeds is a 403 at runtime; a screen with no UC is SCR-005; the same (entity, type, mode) twice is a duplicate page.',
    gateRules: ['SCR-002', 'SCR-003', 'XD-005', 'SCR-005'],
    status: allResolved ? 'skipped' : 'conditional',
    ...(allResolved
      ? { skipReason: `entity, permission and ${wantedUcs.length} linked UC(s) resolve; no identical surface in the section` }
      : { condition: 'name the entity, the permission and the UC(s) served — the CLI blocks on an unknown one; a same-surface hit means the screen exists (modify it)' }),
    data: {
      entities: (corpus.entities?.entities ?? []).map((e) => e.name),
      permissionsAvailable: [...new Set([...corpus.rbac.rows.map((r) => r.path), ...floor])].sort(),
      sameSurface: sameSurface.map((m) => m.code),
      sectionScreens: corpus.screens.filter((s) => s.section.toLowerCase() === section.toLowerCase()).map((s) => `${s.code} (${s.screenType}${s.mode ? ` ${s.mode}` : ''} · ${s.entity ?? '?'})`),
    },
  })

  steps.push({
    step: n++,
    phase: 'author',
    title: op === 'add' ? `Write the screen block ${code} (${screenType})` : `Rewrite the screen block ${code}`,
    file,
    skill: 'ba-create-screen',
    subWorkflow: `${levelFileOf(screenType)} — required bullets Entité / Permission / Cas d'usage liés + the type-specific ones; a SmartKanban / SmartCard is the SECOND screen of the list section (a representation, never its own section); a multi-resource section declares its SmartSectionHome`,
    why: 'The heading type picks the page template; the bullets are mined 1:1 into the pagespec.',
    gateRules: ['SCR-001', 'SCR-003', 'SCR-005', 'SCR-020'],
    status: 'required',
    ...(corpus.state.sourcesPresent ? { data: { sources: 'registry present — cite `- **Sources** : SRC-NNN §n` (search via ' + CLI_PATHS.sourcesSearch + ')' } } : {}),
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'Declared related tabs (a detail / edit SmartForm) are valid — prerequisites, budget of the shared tab bar',
    cli: { cliPath: CLI_PATHS.deriveRelatedTabs, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, section, mode: 'validate' }, writes: false },
    why: 'RTV-001..009: the related entity, its FK, its list target and its permission must resolve; inner + related tabs ≤ 7 (warn) / 9 (err).',
    gateRules: ['RTV-001', 'RTV-009', 'SCR-009', 'SCR-014', 'SCR-025'],
    status: isForm ? 'required' : 'conditional',
    ...(isForm ? {} : { condition: 'only for a SmartForm in detail / edit mode' }),
  })

  steps.push({
    step: n++,
    phase: 'check',
    title: 'The linked use cases come back `covered` on the BA leg',
    cli: { cliPath: CLI_PATHS.deriveUcCoverage, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module }, writes: false },
    why: 'Proof, not prose — the engine of SCR-024.',
    gateRules: ['SCR-024'],
    status: 'required',
  })

  const prdPresent = corpus.state.pagespecsPresent
  steps.push({
    step: n++,
    phase: 'prd',
    title: folds
      ? `${screenType} produces NO pagespec of its own — it folds into the LIST pagespec (${target.entity ?? '<Entity>'}.list.md): \`viewModes\` + the \`kanban\` block`
      : `NEW pagespec \`${expected ?? '<Entity>.<view>.md'}\` through the Single-pagespec entry point`,
    file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/${expected ?? `${target.entity ?? '<Entity>'}.list.md`}`,
    skill: 'ba-create-prd',
    subWorkflow: folds
      ? 'derive-kanban-spec --mode derive folds a SmartKanban (columns anchored on the enum, BR Flow transitions); a SmartCard is `viewModes` += cards on the list pagespec — json block only'
      : '§ Single-pagespec entry point (screenCode / permission / entity verbatim, `routeFamily` + `routeParent` on a satellite, columns/actions/filters mined 1:1) + the `prd.frontend.md` line',
    ...(folds && screenType === 'SmartKanban' ? { cli: { cliPath: CLI_PATHS.deriveKanbanSpec, spec: { moduleRoot, pagespecDir, mode: 'derive' }, writes: true } } : {}),
    why: 'Every screen needs its pagespec (PRD-070) — except the two representations, which fold (PRD-117 / PRD-135). Never /ba-create-prd on a module with pagespecs.',
    gateRules: folds ? ['PRD-117', 'PRD-135'] : ['PRD-070', 'PRD-108', 'PRD-114'],
    status: prdPresent ? 'required' : 'skipped',
    ...(prdPresent ? {} : { skipReason: 'no pagespecs/ — the module has no PRD yet; /ba-create-prd is legitimate here (nothing to lose).' }),
    data: { expectedPagespec: expected, exists: expected !== null && (corpus.pagespecs ?? []).some((p) => p.name === expected) },
  })

  steps.push({
    step: n++,
    phase: 'derive',
    title: 'Backfill the business-rule links, then the form / detail derivations of the new pagespec',
    cli: { cliPath: CLI_PATHS.deriveRuleLinks, spec: { baRoot: '<baRoot>', app: corpus.scope.app, module: corpus.scope.module, mode: 'backfill' }, writes: true },
    why: 'PRD-129/130; then `derive-lifecycle --mode derive` (a form), `derive-form-sections` (sections), `derive-detail-summary --mode derive` (a detail), `derive-related-tabs --mode validate` with `pagespecs: true`.',
    gateRules: ['PRD-129', 'PRD-130', 'PRD-120', 'PRD-111', 'PRD-134', 'PRD-103'],
    status: prdPresent && !folds ? 'required' : 'skipped',
    ...(prdPresent && !folds ? {} : { skipReason: folds ? 'a representation folds into an existing pagespec — its derivations already ran.' : 'no pagespecs/ yet.' }),
    data: {
      alsoRun: [
        ...(isForm && (target.mode ?? 'edit') !== 'detail' ? [CLI_PATHS.deriveLifecycle + ' mode:derive', CLI_PATHS.deriveFormSections + ' mode:derive'] : []),
        ...(isForm && (target.mode ?? 'edit') === 'detail' ? [CLI_PATHS.deriveDetailSummary + ' mode:derive', CLI_PATHS.deriveRelatedTabs + ' mode:validate pagespecs:true'] : []),
      ],
    },
  })

  steps.push({
    step: n++,
    phase: 'derive',
    title: 'A new `routeFamily` (satellite) needs its nav resource',
    cli: { cliPath: CLI_PATHS.deriveNavResources, spec: { moduleRoot }, writes: false },
    why: 'A registry componentKey whose node Phase 0 never seeded is unreachable (DEV-UI-046).',
    gateRules: ['DEV-UI-046'],
    status: 'conditional',
    condition: 'only when the pagespec declares a `routeFamily` (a satellite of the section)',
  })

  if (op === 'modify') {
    steps.push({
      step: n++,
      phase: 'prd',
      title: 'The existing pagespec follows the screen — json block only; compute-page-diff will mark it `modified`',
      file: `${corpus.scope.app}/${corpus.scope.module}/pagespecs/${expected ?? '<Entity>.<view>.md'}`,
      why: 'Columns / fields / filters / actions mined 1:1; uiDesign, lifecycle, sections, kanban, summary keys untouched.',
      gateRules: ['PRD-070'],
      status: prdPresent ? 'required' : 'skipped',
      ...(prdPresent ? {} : { skipReason: 'no pagespecs/ yet.' }),
    })
  }

  steps.push(auditStep(n++, ctx, ['screens', 'cross-dimension']))
  steps.push(
    handoffStep(n++, ctx, [
      'Phase 0 — only when a new resource / routeFamily was declared (additive seed)',
      'Phase 2b — DEV-API-012: the pagespec view needs its screen-controller endpoint',
      'Phase 3 — the added / modified pagespec lands in compute-page-diff.toRegenerate',
      'Phase 4 — always',
    ]),
  )
  return steps
}

// ---------------------------------------------------------------------------
// dispatch
// ---------------------------------------------------------------------------

export function buildImpact(ctx: ImpactContext): ImpactStep[] {
  switch (ctx.kind) {
    case 'use-case':
      return useCaseImpact(ctx)
    case 'business-rule':
      return ruleImpact(ctx)
    case 'actor':
      return actorImpact(ctx)
    case 'permission':
      return permissionImpact(ctx)
    case 'attribute':
      return attributeImpact(ctx)
    case 'entity':
      return entityImpact(ctx)
    case 'screen':
      return screenImpact(ctx)
    default:
      return []
  }
}