@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/gate-audience.ts

@@ -0,0 +1,171 @@
+/**
+ * Who each governance gate under `packages/aeg-core/bin/` is FOR.
+ *
+ * The problem this closes: this repository holds two parallel worlds — the
+ * gates it runs on itself (`packages/aeg-core/bin/*`) and the checks an
+ * adopter runs through the published CLI (`apps/cli/src/checks/bin/*`) — and
+ * nothing asserted a relationship between them. Membership of the shipped set
+ * was defined by ABSENCE from `coreCheckRegistry()`, which means a deliberate
+ * exclusion and a forgotten port left exactly the same trace.
+ *
+ * `reader-resolvable-prose` is the instructive case, and the reason this file
+ * exists. That call was made carefully and its reasoning written up well — in
+ * a paragraph of prose inside `registry.ts`. It is right, and it is invisible
+ * to tooling. A good decision and an unmade decision looked identical, so the
+ * next one might simply not get made.
+ *
+ * So `internal` is a thing you must SAY, with a reason, rather than something
+ * you can forget to notice. `gate-audience.test.ts` enumerates the bin
+ * directory and fails when a gate is in neither column.
+ *
+ * **This is deliberately NOT a field on `CheckSpec`.** Adopter-defined checks
+ * in `vinaya.config.json` produce that same shape (`lib/config.ts`), so an
+ * `audience` field there would push an internal-governance concept into
+ * adopter-facing config, where it means nothing and cannot be answered.
+ * The question is about THIS repo's own bins, so the declaration lives here.
+ *
+ * Adding a gate to `bin/` and nothing else is now a failing build, naming the
+ * file. That is the whole mechanism; deciding which column a given gate
+ * belongs in stays a human judgement, which is the point.
+ */
+
+/** A gate that adopters run, and the `coreCheckRegistry()` name it ships
+ * under. `ring` mirrors `apps/cli/src/checks/registry.ts`'s `CORE_CHECK_RING`
+ * value for that same name — duplicated here, not imported, because
+ * `aeg-core` cannot import `apps/cli` (see this file's own module comment on
+ * the dependency-cycle constraint `coreCheckRegistry()` runs into). Kept
+ * from drifting by `registry-ring-parity.test.ts` (`apps/cli`), which is the
+ * only place both sides are in scope at once — same shape as
+ * `shipped-bin-audience.test.ts`'s existing `shippedAs` cross-check. This is
+ * the "registry-derived fact" `registry-scaffold.ts` reads to place a stub
+ * row for an aeg-core-bin G2 candidate that IS registry-backed; a candidate
+ * with no entry here gets no stub (see `registry-scaffold.ts`). */
+export type ShippedGate = { shippedAs: string | string[]; ring: 0 | 1 | 2 }
+/** A gate this repo runs on itself, and why it cannot or should not ship. */
+export type InternalGate = { internal: string }
+export type GateAudience = ShippedGate | InternalGate
+
+/**
+ * Keyed by basename (no extension) of each `packages/aeg-core/bin/*.ts` that
+ * is a GATE — something that inspects a repo and passes or fails. Non-gate
+ * tooling in the same directory (forge writers, one-shot reporters) is listed
+ * in `NON_GATE_BINS` below rather than given a fake audience.
+ */
+export const GATE_AUDIENCE: Record<string, GateAudience> = {
+  'check-branch-topology': { shippedAs: 'branch-topology', ring: 0 },
+  'check-first-push-dispatch': { shippedAs: 'first-push-dispatch', ring: 0 },
+  'check-no-disk-state': { shippedAs: 'no-disk-state', ring: 0 },
+  'verify-brief': { shippedAs: 'brief-shape', ring: 0 },
+  'verify-coherence': { shippedAs: 'coherence', ring: 0 },
+  'verify-dispatch': { shippedAs: 'dispatch-readiness', ring: 0 },
+  'verify-docs': { shippedAs: ['doc-coverage', 'doc-coverage-push'], ring: 0 },
+  'verify-registry': { shippedAs: 'registry-gates', ring: 0 },
+  'verify-review-gate': { shippedAs: 'review-gate', ring: 1 },
+  'verify-single-plan-pr': { shippedAs: 'single-plan-pr', ring: 0 },
+  'verify-test-plan': { shippedAs: 'test-plan', ring: 1 },
+
+  'check-direct-main-push': {
+    internal:
+      'Reaches adopters through `vinaya audit --only=direct-push`, not the check registry: it is a ring-2 sweep over merge history keyed on `GITHUB_SHA`, run by the generated archivist job on push to the default branch. It has no diff to key on, so there is nothing for `vinaya check` to run it against.'
+  },
+  'check-push-target': {
+    internal:
+      'A pre-push hook helper: it takes a branch name as `argv[2]` and answers one `gh pr list --head <branch>` question, for a caller that already knows which ref is being pushed. Adopters reach the same question through the registered `dead-branch-push`, which resolves the branch itself when `BRANCH` is unset. Registering this one too would add a second entry answering an identical forge query with a worse interface.'
+  },
+  'verify-task': {
+    internal:
+      "A composite that shells this repo's own `typecheck`/`lint`/`test`/`build` scripts by name. Those names are this monorepo's toolchain (bun + turbo + biome), not an adopter's; the shipped equivalent of its intent is `vinaya check --all`, which is portable by construction."
+  }
+}
+
+/**
+ * The other half, and the one the motivating case actually lives in.
+ *
+ * `reader-resolvable-prose` has no bin under `packages/aeg-core/bin/` at all —
+ * its logic is `src/reader-resolvable-prose.ts` and its only executable is
+ * `apps/cli/src/checks/bin/check-reader-resolvable-prose.ts`. So the map above
+ * would never have seen it, and an earlier revision of this file claimed it as
+ * the reason the file exists while leaving it uncovered. Review caught that;
+ * this is the fix, not a re-wording.
+ *
+ * Enumerating the SHIPPED check bins asks the question that case actually
+ * poses: here is an executable adopters could run — is it registered, and if
+ * not, why not? `coreCheckRegistry()` lives in `apps/cli`, which `aeg-core`
+ * cannot import without closing a dependency cycle, so the declaration lives
+ * here and `apps/cli`'s own suite does the asserting.
+ *
+ * `check-reader-resolvable-prose`/`check-retired-vocabulary` (task 7, Issue
+ * #56): both used to live here as `internal` — hardcoded monorepo-specific
+ * doctrine paths made them unreachable through an adopter's own registry.
+ * Both are now config-driven (`vinaya.config.json`'s `proseGates`) and
+ * registered in `coreCheckRegistry()` as `reader-resolvable-prose` /
+ * `retired-vocabulary`, so neither belongs in this map any more — this repo's
+ * own `shipped-bin-audience.test.ts` refuses a bin declared in BOTH places.
+ */
+export const SHIPPED_BIN_AUDIENCE: Record<string, GateAudience> = {}
+
+/**
+ * `name` -> `ring` for every check registered in `coreCheckRegistry()` whose
+ * bin lives under `apps/cli/src/checks/bin/` — the direct analogue of
+ * `ShippedGate.ring` above, for the OTHER directory. Mirrors
+ * `apps/cli/src/checks/registry.ts`'s `CORE_CHECK_RING` — duplicated, not
+ * imported, for the identical dependency-cycle reason `ShippedGate.ring`'s
+ * own comment gives: `aeg-core` cannot import `apps/cli`. This is the
+ * registry-derived fact `registry-scaffold.ts` reads to place a stub row for
+ * an `apps/cli/src/checks/bin/` G2 candidate; a bin whose stripped name has
+ * no entry here gets no stub — same no-guess discipline `classify()`
+ * already applies to `packages/aeg-core/bin/` candidates via
+ * `GATE_AUDIENCE`. Kept from drifting by `shipped-bin-audience.test.ts`
+ * (`apps/cli`)'s own ring-parity block, the only place both sides are in
+ * scope at once — same shape as this file's `ShippedGate.ring` check.
+ */
+export const CLI_CHECK_RING: Readonly<Record<string, 0 | 1 | 2>> = {
+  'brief-shape': 0,
+  'pr-report-density': 0,
+  'doc-coverage': 0,
+  coherence: 0,
+  'dispatch-readiness': 0,
+  'closes-n': 1,
+  'single-plan-pr': 0,
+  'test-plan': 1,
+  'body-bare-digits': 1,
+  'no-disk-state': 0,
+  'registry-gates': 0,
+  'review-gate': 1,
+  'branch-topology': 0,
+  'dead-branch-push': 0,
+  'first-push-dispatch': 0,
+  'doc-coverage-push': 0,
+  'issue-assignment': 0,
+  'evidence-fresh': 1,
+  'reader-resolvable-prose': 0,
+  'retired-vocabulary': 0,
+  'doctrine-no-procedures': 0,
+  'doctrine-portability': 0,
+  'workspace-escape': 0,
+  'exec-bits': 0,
+  'changeset-coverage': 0,
+  'quoted-command': 0,
+  'main-branch-refusal': 0,
+  'token-collection-wired': 0,
+  'token-report': 1
+}
+
+/**
+ * Files in `bin/` that are not gates and therefore have no audience: forge
+ * writers and one-shot reporters. Listed explicitly rather than pattern-matched
+ * so a NEW file cannot slip through by being named unlike a gate.
+ */
+export const NON_GATE_BINS = [
+  'archive-task',
+  'assign-task-issue',
+  'dead-branch-audit',
+  'eval-agent-compliance',
+  'open-issue',
+  'open-pr',
+  'report-tokens'
+] as const
+
+export function isShipped(a: GateAudience): a is ShippedGate {
+  return 'shippedAs' in a
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/index.ts

@@ -0,0 +1,323 @@
+export * from './types'
+export type { StateSource } from './state-source'
+export type { DoctrineContent, DoctrineSource } from './doctrine-source'
+export { CLI_CHECK_RING, GATE_AUDIENCE, NON_GATE_BINS, SHIPPED_BIN_AUDIENCE, isShipped } from './gate-audience'
+export type { GateAudience, InternalGate, ShippedGate } from './gate-audience'
+export { ANCHOR_FIELDS, anchoredRegion, anchoredRegionBounds } from './anchored-region'
+export type { AnchorField } from './anchored-region'
+export { parseRegistry } from './parse-registry'
+export {
+  CROSS_CUTTING_CANDIDATES,
+  deriveBuiltinCrossCuttingDefaults,
+  deriveWorkspacePackageDomains,
+  parsePnpmWorkspaceYaml,
+  resolveWorkspaceEntry
+} from './blast-radius-domains'
+export { buildConsumersOf, deriveWorkspaceMemberDirs } from './consumer-enumeration'
+export type { PackageManifest } from './consumer-enumeration'
+export { parseTranche } from './parse-tranche'
+export { deriveTranche } from './derive-tranche'
+export { parseLedger, rowFromCells } from './parse-ledger'
+export { sumLedger } from './sum-ledger'
+export { aggregateTaskTokenRows, parseTokenReportEntries, parseTokensLines } from './parse-token-report'
+export type { TokenSourcePr } from './parse-token-report'
+export { deriveReviewStatus, parseDeveloperRoundMarker, renderReviewStatus } from './review-status'
+export type { ReviewStatus, ReviewStatusInput } from './review-status'
+export { formatBreakdown, formatTokenReportRow, formatTokensLine } from './report-tokens'
+export type { TokenReportRowInput, TokensLineInput, TranscriptSummary, UsageComponents } from './report-tokens'
+// The Claude Code collection adapter (`tranche-model.md` §12 layer 2) — one
+// host's way to produce a `TranscriptSummary`, exported beside the portable
+// renderers it feeds, never as a requirement of the contract.
+export {
+  isTokenCollectionWiringBroken,
+  resolveMeteringCapability,
+  summarizeTranscript
+} from './claude-code-transcript'
+export type { MeteringCapability, MeteringCapabilityDeps, MeteringIncapableReason } from './claude-code-transcript'
+// The hardened deps every real caller of `resolveMeteringCapability` should
+// build from (`#313`) — a sibling module, not part of the pure adapter above.
+export { hardenedMeteringDeps, isTrustedMeteringStat } from './metering-io-guard'
+export { declarationsIn, findCollisions } from './symbol-collisions'
+export type { SymbolCollision, SymbolDeclaration } from './symbol-collisions'
+export { isCodeFile, isDocFile, isSpecFile } from './file-classify'
+export { hasStatusBlock } from './status-block'
+export {
+  classifyDocOwnersManifest,
+  DOC_OWNERS_PATH,
+  evaluateC5,
+  globToRegex,
+  isMechanicallyNeutralDiff,
+  isUrlPointer,
+  parseDocOwners,
+  pointerToPath,
+  readDocAcks,
+  readDocNeutrals
+} from './doc-owners'
+export type { C5Result, DocAck, DocNeutral, DocOwnersBinding, DocOwnersManifestState } from './doc-owners'
+export {
+  isPrincipal,
+  isWaiverLabelActorVerified,
+  PRINCIPAL_ALLOWLIST,
+  WAIVER_LABEL,
+  WAIVER_LABEL_REVIEW
+} from './waiver-label'
+export { deriveSection7, globsOverlap } from './derive-section7'
+export type { Section7Match } from './derive-section7'
+export { checkManifestValidity, parseNoDocRules } from './manifest-validity'
+export type { NoDocRule } from './manifest-validity'
+export { evaluateVocabularyCitation } from './vocabulary-citation'
+export type {
+  VocabularyCheckResult,
+  VocabularyFinding,
+  VocabularyHit,
+  VocabularyPattern
+} from './vocabulary-citation'
+export { deriveTierFromDiff, overrideActive, readTierFromPrBody, TIER_FIELD } from './pr-tier'
+export {
+  checkAutonomyClause,
+  checkBriefSections,
+  checkClosesN as checkBriefClosesN,
+  checkCommandsCarryOutput,
+  checkConsumerTests,
+  checkDefeatCases,
+  checkDocUpdateList,
+  checkForField,
+  checkForgeTitle,
+  checkNoAgentBoxes,
+  checkNoUnpinnedCodeClaims,
+  checkPlanPrNoCloses,
+  checkPremiseCoverage,
+  checkPrincipalPlaceholder,
+  checkProjectField,
+  checkStopConditions,
+  checkSurfaceMap,
+  checkTestPlan,
+  checkTestPlanExclusivity,
+  checkTierField,
+  checkWorktreeStep0,
+  AGENT_BOXES_REFUSED_SINCE_PR,
+  BRIEF_RULES_SINCE_PR,
+  COMMAND_WORDS,
+  COMMIT_TYPE_STYLE,
+  COMMIT_TYPES,
+  extractFencedBlocks,
+  headerRegion,
+  inferBranchFromBody,
+  isBriefShaped,
+  isGrandfatherableBriefRuleError,
+  isTaskBranch,
+  partitionBriefErrorsByRollout
+} from './brief-validation'
+export type { BriefSectionResult, BriefSectionsOptions, FencedBlock } from './brief-validation'
+export { checkDoctrineNoProcedures } from './doctrine-no-procedures'
+export type { DoctrineFile, DoctrineProcedureFinding } from './doctrine-no-procedures'
+export { checkPrReportDensity, checkScopeDensity, checkSummaryDensity } from './pr-report-density'
+export type { DensityResult } from './pr-report-density'
+export {
+  checkA1,
+  checkA2,
+  checkA3,
+  checkClosesN,
+  checkD1,
+  checkL1,
+  checkL2,
+  checkL3,
+  checkL4,
+  checkL5,
+  checkR1,
+  checkT1,
+  checkT2,
+  checkT3,
+  COHERENCE_ENFORCED_FROM,
+  extractClosesReferences,
+  isGrandfathered,
+  R1_GRANDFATHERED_ISSUES,
+  scopeT2ToPlanPr
+} from './coherence-checks'
+export type { CheckFailure, CheckResult, ForgeIssue, TrancheFile, TaskEntry } from './coherence-checks'
+export {
+  buildProvenanceBlock,
+  extractIssue,
+  hasProvenance,
+  isEligibleForProvenance,
+  taskRefFromBranch
+} from './archive-task'
+export type { MergedPrFacts } from './archive-task'
+export { extractCodeReviewVerdict, extractSecurityReviewVerdict } from './verdict-extraction'
+export type { VerdictExtraction } from './verdict-extraction'
+export {
+  CHANGESET_RELEASE_BRANCH,
+  checkReviewGate,
+  DEFAULT_RELEASE_ACTOR,
+  isChangesetsReleasePr,
+  isReviewGateExemptBranch
+} from './review-gate'
+export type { ReviewGateComment, ReviewGateInput, ReviewGateResult, ReviewGateVerdict } from './review-gate'
+export {
+  checkBlastRadiusScope,
+  checkConflictCompleteness,
+  checkIssueRationale,
+  checkIssueType,
+  checkNoBriefContent,
+  checkProjectsRegistered,
+  checkRationaleNamesDocs,
+  declaredProjects,
+  isTaskIssueLabelSet
+} from './issue-validation'
+export type { IssueSectionResult, ProjectPath, TaskIssueFacts } from './issue-validation'
+export { findHeadingLine, findTable, rowToRecord } from './markdown-table'
+export type { ParsedTable, TableRow } from './markdown-table'
+export { deriveDiagramModel } from './diagram-model'
+export type {
+  DiagramConfig,
+  DiagramEdge,
+  DiagramFinding,
+  DiagramModel,
+  DiagramNode,
+  DiagramNodeKind,
+  RenderState
+} from './diagram-model'
+export { parseEnforcementRegistry } from './registry-parse'
+export type { GateRing, GateRow } from './registry-parse'
+export { checkG1, checkG2, checkG3, checkG4, checkG5, checkG6 } from './registry-checks'
+export type { RegistryCheckResult, RegistryCheckStatus, RegistryFinding } from './registry-checks'
+export { applyScaffoldPlan, computeScaffoldPlan, PLACEHOLDER } from './registry-scaffold'
+export type { ScaffoldPlan, ScaffoldSkip, ScaffoldStub } from './registry-scaffold'
+export { ACTIONS, CROSSING_KEYWORDS } from './actions'
+export type { Action, ActionCrossing } from './actions'
+export {
+  DERIVABLE_STATUSES,
+  DERIVATION_RULES,
+  DERIVED_STATUSES,
+  deriveStatusFromModel,
+  FORGE_FACT_INPUTS
+} from './state-machine-model'
+export type { DerivationRule, ForgeFactInput } from './state-machine-model'
+export { checkPremises, parsePremiseBlock } from './premise-check'
+export type { PremiseAssertion, PremiseCheckResult } from './premise-check'
+export { classifyLeftover } from './leftover-detection'
+export type { LeftoverInput, LeftoverResult, LeftoverVerdict } from './leftover-detection'
+export { checkDeadBranchPush } from './dead-branch-push-guard'
+export type {
+  DeadBranchPushInput,
+  DeadBranchPushResult,
+  DeadBranchPushVerdict,
+  PrStateFact
+} from './dead-branch-push-guard'
+export { captureBaseline, compareToBaseline } from './baseline-capture'
+export type { BaselineComparison, BaselineEntry, BaselineToolComparison } from './baseline-capture'
+export { checkDoctrinePortability } from './doctrine-portability'
+export type { PortabilityFinding, PortabilitySourceFile } from './doctrine-portability'
+export {
+  checkReaderResolvableProse,
+  checkUndefinedVocabulary,
+  checkUnresolvableReferences,
+  classifyProseFile,
+  legacySlugPattern,
+  parseGlossaryTerms,
+  stripNonProse
+} from './reader-resolvable-prose'
+export type { ProseFileClass, ProseFinding, ProseSourceFile } from './reader-resolvable-prose'
+export {
+  checkQuotedCommandStaleness,
+  evaluateCitedQuotes,
+  findCitedQuotes,
+  isValidCitedFilePath
+} from './quoted-command'
+export type { CitedQuote, QuotedCommandFinding, QuotedCommandSourceFile } from './quoted-command'
+export {
+  PATTERN_EXEMPT,
+  RETIRED_EXEMPT_SUBSTRINGS,
+  RETIRED_PATTERNS,
+  scanRetiredVocabulary
+} from './retired-vocabulary'
+export type { VocabFinding, VocabSourceFile } from './retired-vocabulary'
+export { checkLocalAnchorCoverage } from './local-anchor-coverage'
+export type {
+  AnchorCoverageFinding,
+  AnchorCoverageScope,
+  AnchorSourceFile,
+  LocalAnchorCoverageOptions,
+  LocalAnchorCoverageResult
+} from './local-anchor-coverage'
+export { checkDispatchReadiness } from './dispatch-gate'
+export type {
+  DispatchConflictsWithFact,
+  DispatchDependsOnFact,
+  DispatchEdgeFact,
+  DispatchGateInput,
+  DispatchIssueFact,
+  DispatchPriorTrancheFact,
+  DispatchPriorTaskFact,
+  DispatchResult
+} from './dispatch-gate'
+export { checkSinglePlanPr, trancheSlugFromTopologyPath, touchesAnyTopology } from './single-plan-pr'
+export type { OpenPrFiles } from './single-plan-pr'
+export { isNewDiskStateFile } from './no-disk-state'
+export type { DiskStateFileStatus } from './no-disk-state'
+export { checkDirectMainPush } from './direct-main-push'
+export type { DirectMainPushFact, DirectMainPushResult } from './direct-main-push'
+export { checkMainBranchRefusal } from './main-branch-refusal'
+export type { MainBranchRefusalFinding, MainBranchRefusalReason } from './main-branch-refusal'
+export { ensureLabelExists, LABEL_COLOR } from './ensure-label'
+export type { LabelExistenceIo } from './ensure-label'
+export { findDeadBranchPushes } from './dead-branch-push-audit'
+export type { DeadBranchFact, DeadBranchPush } from './dead-branch-push-audit'
+export { checkBranchTopology, taskBranchTopologyFields } from './branch-topology-gate'
+export type { BranchTopologyInput, BranchTopologyResult, BranchTopologyVerdict } from './branch-topology-gate'
+export { checkFirstPushDispatchGate, parseTaskBranch } from './first-push-dispatch-gate'
+export type {
+  DispatchReadinessFact,
+  FirstPushDispatchGateInput,
+  FirstPushDispatchGateResult,
+  FirstPushDispatchGateVerdict
+} from './first-push-dispatch-gate'
+export { decideIssueAssignment } from './issue-assignment'
+export type { IssueAssignmentDecision, IssueAssignmentInput } from './issue-assignment'
+export { locateTestPlanSection } from './test-plan-section'
+export type { TestPlanSection } from './test-plan-section'
+export { evaluateTestPlanGate } from './test-plan-gate'
+export type { TestPlanGateResult, TestPlanGateVerdict } from './test-plan-gate'
+export {
+  AEG_BLOCKED_LABEL,
+  buildBranchName,
+  fetchForgeFacts,
+  fetchForgeTasksByLabel,
+  fetchOpenIssuesByLabel,
+  fetchTaskIssueRefs,
+  findTrancheSlug,
+  hasLabel,
+  trancheLabel,
+  trancheSlugLengthError,
+  trancheSlugOf,
+  LABEL_MAX_LENGTH,
+  LABEL_NAMESPACE,
+  LABELS,
+  label,
+  mapForgeFacts,
+  matchesLabel,
+  projectsFromBody
+} from '@attalabs/aeg-forge-state'
+export type { Label, LabelCategory, LabelForm, LabelKey } from '@attalabs/aeg-forge-state'
+export type {
+  FetchForgeFactsInput,
+  ForgeFactsSnapshot,
+  PrRef,
+  RawTaskFacts,
+  TaskIssueRef,
+  TaskRef
+} from '@attalabs/aeg-types'
+export { checkAdoptable, checkMilestoneShape, releaseFieldFromBody } from './milestone-validation'
+export type {
+  AdoptFacts,
+  AdoptResult,
+  AdoptSlugFacts,
+  AdoptTargetFacts,
+  MilestoneIntent,
+  MilestoneShapeResult,
+  ReleaseField
+} from './milestone-validation'
+export { findWorkspaceEscapes } from './workspace-escape'
+export type { WorkspaceEscapeFinding, WorkspaceEscapeReason, WorkspaceEscapeSourceFile } from './workspace-escape'
+export { parseRationaleFields, renderBrief } from './brief-render'
+export type { BriefFacts, RationaleFieldKey, RenderResult, SurfaceFileFact } from './brief-render'

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/issue-assignment.ts

@@ -0,0 +1,102 @@
+import { parseTaskBranch } from './first-push-dispatch-gate'
+
+/**
+ * First-push Issue self-assignment (aeg-governance-hardening task 33, #401).
+ * Pure — no `fs`, no `gh`/`git` shell-outs. The CLI shim
+ * (`bin/assign-task-issue.ts`, wired into `.husky/pre-push`) gathers the
+ * facts — does the remote ref already exist, which Issue does the topology
+ * row name, who is currently assigned, who is the authenticated pusher —
+ * and this evaluator decides whether to assign.
+ *
+ * Produces the signal Studio's dispatch-visibility chip (task 26, #368)
+ * renders: `facts.assigned = assigneesCount > 0`. Assignment had never been
+ * mechanized anywhere — it happened only when the Principal remembered to
+ * assign by hand, so a genuinely in-flight task (task 28, #372: two real
+ * commits pushed) looked identical to an untouched one. The task branch's
+ * FIRST real push is the earliest genuine "in flight" evidence (assigning
+ * at brief-authoring time would reintroduce the false positive task 26 was
+ * built to avoid), so that is the moment this fires.
+ *
+ * Every guard skips rather than errors — this is a visibility nicety, never
+ * a gate. In particular: `assignees`/`login` arriving as `null` (a failed
+ * `gh` call) means "no signal", and no-signal means no action — never a
+ * guess, never a block.
+ */
+
+export type IssueAssignmentInput = {
+  /** The branch being pushed. */
+  branch: string
+  /**
+   * Whether the remote ref already exists — from the pre-push stdin's
+   * remote-sha (all zeros = the ref is being created by this push, i.e.
+   * genuinely the first push). A force-push to an existing branch keeps a
+   * non-zero remote-sha and therefore never re-triggers; deleting and
+   * recreating the remote branch re-presents a zero sha, which the
+   * already-assigned no-op below absorbs.
+   */
+  remoteRefExists: boolean
+  /** The topology row's Issue number, or `null` when the row or its Issue cell could not be resolved. */
+  issue: number | null
+  /** Current assignee logins on the Issue, or `null` when the fetch failed. */
+  assignees: string[] | null
+  /** The authenticated `gh` login — the actual pusher — or `null` when unresolvable. Never a hardcoded fallback. */
+  login: string | null
+}
+
+export type IssueAssignmentDecision =
+  | { action: 'assign'; issue: number; login: string; reason: string }
+  | { action: 'skip'; reason: string }
+
+export function decideIssueAssignment(input: IssueAssignmentInput): IssueAssignmentDecision {
+  const { branch, remoteRefExists, issue, assignees, login } = input
+
+  if (parseTaskBranch(branch) === null) {
+    return {
+      action: 'skip',
+      reason: `Branch \`${branch}\` is not a task/<tranche>/<n> branch — Issue self-assignment only applies to task branches.`
+    }
+  }
+
+  if (remoteRefExists) {
+    return {
+      action: 'skip',
+      reason: `Branch \`${branch}\` already exists on the remote — not its first push, nothing to assign.`
+    }
+  }
+
+  if (issue === null) {
+    return {
+      action: 'skip',
+      reason: `No Issue resolved for \`${branch}\` from its topology row — skipping self-assignment (the gate owns refusing an unplanned branch).`
+    }
+  }
+
+  if (assignees === null) {
+    return {
+      action: 'skip',
+      reason: `Could not read Issue #${issue}'s current assignees — skipping rather than risking a double-assign (fail-open, never a guess).`
+    }
+  }
+
+  if (assignees.length > 0) {
+    return {
+      action: 'skip',
+      reason: `Issue #${issue} is already assigned (${assignees.join(', ')}) — no-op.`
+    }
+  }
+
+  if (login === null) {
+    return {
+      action: 'skip',
+      reason:
+        'Could not resolve the authenticated `gh` login — never assigning anyone other than the actual pusher, so skipping.'
+    }
+  }
+
+  return {
+    action: 'assign',
+    issue,
+    login,
+    reason: `First push of \`${branch}\` — assigning Issue #${issue} to @${login} (the authenticated pusher).`
+  }
+}