docs(adr): record accepted mirt fit-search decisions

Add docs/adr/ for decisions already true on develop: mirt delegation,
Zh / S-X2 / Rasch infit gates, AICc and DIC boundaries, and local
default as an independent R package. Point ARCHITECTURE.md, README,
and docs/papers/README.md at the new index.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>

Author: cursoragent

ARCHITECTURE.md

@@ -1,10 +1,11 @@
 # kaefa Architecture
 
-Last updated: 2026-02-14
+Last updated: 2026-08-25
 
 ## Purpose
 
 `kaefa` is an R package for automated exploratory factor analysis (AEFA).
+Accepted decisions already true on this branch are recorded in `docs/adr/`.
 It provides:
 
 - core AEFA execution (`aefa`, `engineAEFA`),

README.Rmd

@@ -17,6 +17,8 @@ knitr::opts_chunk$set(
 
 The goal of kaefa is to improve researchers' ability to identify unexplained factor structures in complex, cross-classified multilevel data in R. It uses an automated exploratory factor analysis (aefa) framework.
 
+Accepted fit-search decisions are recorded in [`docs/adr/`](docs/adr/).
+
 ## Algorithm
 
 The automated exploratory factor analysis (aefa) framework implements a **greedy search algorithm** to efficiently explore the model space and find improved model configurations. The algorithm iteratively:

README.md

@@ -10,6 +10,8 @@ unexplained factor structures in complex, cross-classified multilevel
 data in R. It uses an automated exploratory factor analysis (aefa)
 framework.
 
+Accepted fit-search decisions are recorded in [`docs/adr/`](docs/adr/).
+
 ## Algorithm
 
 The automated exploratory factor analysis (aefa) framework implements a

docs/adr/0001-mirt-estimation-delegation.md

@@ -0,0 +1,38 @@
+# ADR 0001: Delegate IRT/EFA estimation and item-fit to mirt
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+kaefa searches unexplained factor structures by fitting candidate IRT/EFA
+models and pruning poorly fitting items. The heavy estimation (MML-EM,
+rotation, item-fit statistics) is already implemented and validated in
+`mirt`. Re-implementing those internals in kaefa would duplicate a
+maintained package and drift from its published definitions.
+
+## Decision
+
+IRT/EFA estimation and item-fit statistics are delegated to `mirt`
+(Chalmers, 2012). kaefa owns the search loop and the decision rules on
+top: `engineAEFA()` estimates candidates through `.mirt` / `.mixedmirt`
+wrappers, `evaluateItemFit()` calls `mirt::itemfit()`, and `aefa()`
+selects and prunes from that output.
+
+kaefa does not re-implement `P(theta)`, the MML-EM E-/M-step, `S-X2`,
+`infit`, or `outfit`. Those remain `mirt`'s responsibility.
+
+## Consequences
+
+- Fit numbers consumed by the search (`Zh`, `S-X2`, `infit`/`outfit`)
+  come from `mirt` and stay subject to `mirt`'s validation.
+- Package-local rules (cutoffs, AICc reconstruction, the DIC boundary)
+  are recorded in later ADRs and pinned in `docs/papers/README.md`.
+- A `mirt` version change can change numeric output without a kaefa
+  formula change.
+
+## References
+
+Chalmers, R. P. (2012). mirt: A multidimensional item response theory
+package for the R environment. *Journal of Statistical Software, 48*(6),
+1–29. https://doi.org/10.18637/jss.v048.i06

docs/adr/0002-zh-misfit-decision-rule.md

@@ -0,0 +1,46 @@
+# ADR 0002: Standardised log-likelihood misfit Zh decision rule
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+The search must decide when an item is misfitting so it can be removed
+and the candidate re-estimated. `mirt::itemfit(fit_stats = "Zh")`
+supplies the standardised log-likelihood statistic of Drasgow, Levine,
+and Williams (1985). kaefa applies a local cutoff; it does not
+re-implement `mirt`'s `Zh` internals.
+
+## Decision
+
+The published statistic, pinned in `docs/papers/README.md`, is
+
+    Zh = (l0 - E[l0]) / sqrt(Var[l0])
+
+An item is flagged as misfitting when
+
+    Zh + qnorm(0.975) / sqrt(n)  <  qnorm(fitIndicesCutOff / 2)
+
+That is a one-sided lower-tail test at level `fitIndicesCutOff / 2` with
+the small-sample correction `qnorm(0.975) / sqrt(n)`. With the default
+`fitIndicesCutOff = 0.005` the threshold is `qnorm(0.0025) = -2.807`.
+
+The arithmetic lives in `.zhMisfitCount()` in `R/kaefa.R` and is applied
+at the three search sites (rotation scan, best-candidate check, and the
+final `ZhCond` gate). Those three sites must stay identical.
+
+## Consequences
+
+- Drift between the three sites changes which rotations and items the
+  search treats as misfitting. A 2019 debug commit dropped `/sqrt(n)`
+  from one site; the shared helper exists to prevent that class of
+  inconsistency.
+- `Zh` itself remains a `mirt` computation. Audits compare the local
+  cutoff to the pinned equation, not a re-derived `Zh`.
+
+## References
+
+Drasgow, F., Levine, M. V., & Williams, E. A. (1985). Appropriateness
+measurement with polychotomous item response models and standardized
+indices. *British Journal of Mathematical and Statistical Psychology,
+38*(1), 67–86. https://doi.org/10.1111/j.2044-8317.1985.tb00817.x

docs/adr/0003-sx2-rmsea-misfit-gates.md

@@ -0,0 +1,41 @@
+# ADR 0003: S-X2 and RMSEA.S_X2 misfit gates
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+`Zh` is not the only item-fit gate in the search. When `mirt::itemfit()`
+returns Orlando and Thissen (2000) `S-X2` columns, kaefa also uses the
+limited-information p-value and the RMSEA computed from that statistic.
+
+## Decision
+
+kaefa flags misfit from `S-X2` when either of these holds
+(`R/kaefa.R`):
+
+- `p.S_X2 < fitIndicesCutOff`
+- `round(RMSEA.S_X2, 2) >= .05`
+
+`S-X2` is computed by `mirt` (`fit_stats = "S_X2"`). The 0.05 RMSEA
+close-fit threshold for limited-information item fit follows
+Maydeu-Olivares and Joe (2014). kaefa does not re-implement `S-X2`.
+
+## Consequences
+
+- Items can be pruned for a significant `S-X2` p-value or for rounded
+  RMSEA at or above 0.05 even when `Zh` is acceptable.
+- Rounding RMSEA to two decimals is part of the accepted gate, not an
+  informal display choice.
+- The statistic and its RMSEA remain `mirt` output; only the gates are
+  package-local.
+
+## References
+
+Orlando, M., & Thissen, D. (2000). Likelihood-based item-fit indices for
+dichotomous item response theory models. *Applied Psychological
+Measurement, 24*(1), 50–64. https://doi.org/10.1177/01466216000241003
+
+Maydeu-Olivares, A., & Joe, H. (2014). Assessing approximate fit in
+categorical data analysis. *Multivariate Behavioral Research, 49*(4),
+305–328. https://doi.org/10.1080/00273171.2014.911075

docs/adr/0004-rasch-infit-outfit.md

@@ -0,0 +1,32 @@
+# ADR 0004: infit and outfit only for Rasch unidimensional models
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+Wright and Masters (1982) mean-square `infit` and `outfit` are Rasch
+fit statistics. `mirt::itemfit(fit_stats = "infit")` can return them,
+but they are not defined for the general multidimensional, non-Rasch
+candidates `engineAEFA()` explores.
+
+## Decision
+
+`evaluateItemFit()` requests `infit` (which also returns `outfit`) only
+when the fitted model has at least one Rasch item type and
+`nfact == 1`. Other models skip that `itemfit` call.
+
+kaefa does not re-implement the mean-square residuals. Computation stays
+in `mirt`.
+
+## Consequences
+
+- Multidimensional or non-Rasch candidates are judged by `Zh` and, when
+  available, `S-X2` / `RMSEA.S_X2`, not by `infit`/`outfit`.
+- A later request for `infit` on a 2PL or multifactor model would be a
+  new decision, not an extension of this one.
+
+## References
+
+Wright, B. D., & Masters, G. N. (1982). *Rating scale analysis*. MESA
+Press.

docs/adr/0005-aicc-dic-criteria.md

@@ -0,0 +1,47 @@
+# ADR 0005: AICc reconstruction and the DIC boundary
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+`aefa()` selects among candidates by an information criterion. Current
+`mirt` fits supply `AIC` and `logLik` but do not consistently expose
+`AICc`. The maximum-likelihood / MAP models from current `mirt`
+versions also do not expose the posterior deviance quantities needed to
+reconstruct DIC.
+
+## Decision
+
+AICc is reconstructed only from the Hurvich and Tsai (1989)
+small-sample correction. When the fit does not already supply a finite
+`AICc`, kaefa recovers `k = (AIC + 2 * logLik) / 2` and applies
+
+    AICc = AIC + 2 * k * (k + 1) / (n - k - 1)
+
+The statistic is undefined when `n <= k + 1`; kaefa reports that reason
+rather than returning a fabricated finite score.
+
+DIC is accepted only when the fitted model supplies a finite posterior
+DIC (Spiegelhalter et al., 2002). DIC is never reconstructed from AIC
+and is never relabelled from AIC. `CAIC` is not treated as an alias for
+`AICc`.
+
+## Consequences
+
+- Default search can use AIC, AICc, BIC, or saBIC without a posterior
+  sample.
+- Requesting DIC on an ML/MAP `mirt` fit that lacks a finite DIC is an
+  error, not a silent fall-back to AIC.
+- Sequential DIF selection also refuses to substitute AIC for DIC.
+
+## References
+
+Hurvich, C. M., & Tsai, C.-L. (1989). Regression and time series model
+selection in small samples. *Biometrika, 76*(2), 297–307.
+https://doi.org/10.1093/biomet/76.2.297
+
+Spiegelhalter, D. J., Best, N. G., Carlin, B. P., & van der Linde, A.
+(2002). Bayesian measures of model complexity and fit. *Journal of the
+Royal Statistical Society: Series B, 64*(4), 583–639.
+https://doi.org/10.1111/1467-9868.00353

docs/adr/0006-local-default-independent-package.md

@@ -0,0 +1,37 @@
+# ADR 0006: Local default and independent R package
+
+- Status: Accepted
+- Date: 2026-08-25
+
+## Context
+
+`ARCHITECTURE.md` describes kaefa as an R package whose runtime path is
+`aefa()` / `engineAEFA()`, with `aefaInit()` available for optional
+worker setup. In the ContextualWisdomLab ecosystem kaefa is a leaf:
+other components may call it, but it must run without those components.
+
+## Decision
+
+Local execution is the default. `aefaInit()` remote workers are
+optional. Hosts may be preconfigured with `options(kaefaServers = ...)`,
+but nothing in the search requires a remote node.
+
+kaefa remains an independent R package (MSA leaf): it is runnable
+without naruon and callable as a dependency. This repository does not
+add sibling-repo checkouts or git submodules for ecosystem components.
+
+## Consequences
+
+- Users can run `aefa()` on a local workstation with the package
+  installed; remote SSH workers are an opt-in.
+- Security-sensitive values (keys, tokens) stay out of git history, as
+  already stated in `ARCHITECTURE.md`.
+- Ecosystem wiring to naruon or sibling repositories is out of scope
+  for this package's default path.
+
+## References
+
+No additional paper. This decision is already stated in
+`ARCHITECTURE.md` (local default; optional `aefaInit()`) and in the
+package `DESCRIPTION` (standalone R package). The allowed citation list
+for this ADR set does not include an execution-topology paper.

docs/adr/README.md

@@ -0,0 +1,17 @@
+# Architecture decision records
+
+This directory records accepted decisions that are already true on `develop`.
+It does not invent product behaviour. Formula provenance and the pinned
+equations remain in [`docs/papers/README.md`](../papers/README.md).
+
+Status dates are 2026-08-25. Citations were live-checked on that date; see
+each ADR's References for the required locator.
+
+| ADR | Decision | Status |
+| --- | --- | --- |
+| [0001](0001-mirt-estimation-delegation.md) | IRT/EFA estimation and item-fit statistics are delegated to `mirt`; kaefa owns search and decision rules | Accepted |
+| [0002](0002-zh-misfit-decision-rule.md) | Standardised log-likelihood misfit `Zh` decision rule | Accepted |
+| [0003](0003-sx2-rmsea-misfit-gates.md) | `S-X2` and `RMSEA.S_X2` misfit gates | Accepted |
+| [0004](0004-rasch-infit-outfit.md) | `infit`/`outfit` requested only for Rasch unidimensional models | Accepted |
+| [0005](0005-aicc-dic-criteria.md) | AICc reconstructed via Hurvich and Tsai; DIC accepted only when `mirt` supplies a finite posterior DIC | Accepted |
+| [0006](0006-local-default-independent-package.md) | Local execution is the default; kaefa remains an independent R package | Accepted |