docs: consolidate FIPC product, research, and licensing guidance

AGENTS.md

@@ -109,4 +109,19 @@ Applies to every agent (Claude, Codex, Cursor, opencode, ...) working in this re
 - For substantive calibration/linking changes, cite the relevant IRT and
   psychometrics literature. Commit paper PDFs only when redistribution is
   permitted; otherwise cite, link, and summarize.
+- Method decisions are recorded in `docs/adr/`. Verified APA 7th records
+  and DOIs are in `docs/papers/README.md`. Do not invent bibliographic
+  records or leave empty `DOI:` placeholders.
+- The implemented linking contract is FIPC (Kim, 2006): anchors keep
+  old-form values. `autoFIPC()` does not estimate a Stocking–Lord (1983)
+  or Haebara (1980) transformation (ADR-0001). Numerical estimation is
+  delegated to `mirt` (ADR-0002), but the returned models are not all one
+  MML-EM path: raw old/new fits may recover through QMCEM, MHRM, and
+  `surveyFA` variants, while the linked fit and IPD/DIF path use EM for
+  nominal items or `tryEM = TRUE` and MHRM otherwise. IPD/DIF screening is
+  not a published invariance claim (ADR-0003).
+- Do not restore Kim and Kolen (2010), "Linking item parameters to a
+  base scale," *Journal of Educational Measurement*. That attribution was
+  incorrect and was removed. The title is Kang and Petersen (2012). A real
+  Kim and Kolen FIPC paper is Kim and Kolen (2019).
 <!-- END cwl-agent-guidance -->

ARCHITECTURE.md

@@ -20,6 +20,9 @@ metadata and CI are wired, and which parts are safe to evolve.
 - `.github/CODEOWNERS` - code ownership map for reviews
 - `.github/dependabot.yml` - Automated Actions dependency updates
 - `.cursor/` - Cloud Agent environment (`environment.json` + `install.sh`)
+- `docs/adr/` - architecture decision records (FIPC contract, mirt engine)
+- `docs/fixed-parameter-item-calibration.md` - Kim (2006) linking contract
+- `docs/papers/README.md` - verified bibliographic sources and DOIs
 - `docs/coderabbit/review-commands.md` - CodeRabbit command quick reference
 - `docs/operations/maintenance-runbook.md` - recurring maintainer operations checklist
 - `README.md` - User/developer entrypoint
@@ -40,11 +43,17 @@ R objects (data frame/matrix/model), and outputs are returned as an R list.
 
 - Path: `R/aFIPC.R`
 - Responsibility:
-  - Calibrate old/new forms using `mirt`
+  - Calibrate old/new forms using `mirt`, with bounded QMCEM/MHRM/`surveyFA`
+    recovery when an initial raw-data fit is unacceptable
   - Optionally detect item parameter drift (IPD)
   - Apply fixed common-item constraints for test linking
+  - Fit the linked model with EM for nominal items or `tryEM = TRUE`, and MHRM
+    otherwise
   - Produce linked model and score/theta artifacts
 - Key dependency: `mirt`
+- Method decision: FIPC (Kim, 2006), not Stocking-Lord (1983) or
+  Haebara (1980) transformation estimation; see
+  `docs/adr/0001-fipc-linking-contract.md`
 
 ### 3.2 Package Metadata and API Surface
 
@@ -105,15 +114,83 @@ package metadata, and CI workflow definitions in Git.
 - Evaluate migration path from historical `packrat/` to a modern
   lock workflow.
 
-## 10. Project Identification
+## 10. Bibliographic grounding
+
+`autoFIPC()` orchestrates FIPC (Kim, 2006): anchors keep old-form
+values and the new form is calibrated onto that scale. That contract
+is an alternative to separate calibration plus Stocking and Lord
+(1983) or Haebara (1980) characteristic-curve linking, and to
+concurrent calibration (Kolen & Brennan, 2014). This repository does
+not implement those transformation estimators.
+
+Numerical estimation lives in `mirt` (Chalmers, 2012). The linked FIPC
+fit uses MML-EM (Bock & Aitkin, 1981) for nominal items or when
+`tryEM = TRUE`, and MHRM otherwise. Separately fitted old/new raw-data
+models can recover through QMCEM, MHRM, and `surveyFA` variants after
+an unacceptable initial fit, so a returned aFIPC result must not be
+summarized as if every model artifact used MML-EM. Optional IPD
+screening calls `mirt::multipleGroup` and `mirt::DIF` with the same
+EM-versus-MHRM selection rule as the linked fit; it is not a published
+invariance claim (see `docs/adr/0003-ipd-dif-screening-delegation.md`).
+Score-scale interpretation is bounded by AERA, APA, and NCME (2014).
+
+An earlier draft incorrectly attributed "Linking item parameters to a
+base scale" to Kim and Kolen (2010) in JEM; that attribution was removed.
+The title belongs to Kang and Petersen (2012). Kim and Kolen (2019) is
+a separate, real later FIPC application paper.
+
+Full APA 7th records and DOIs: `docs/papers/README.md`. Accepted
+method ADRs: `docs/adr/`.
+
+Kim, S. (2006). A comparative study of IRT fixed parameter calibration
+methods. *Journal of Educational Measurement, 43*(4), 355-381.
+<https://doi.org/10.1111/j.1745-3984.2006.00021.x>
+
+Stocking, M. L., & Lord, F. M. (1983). Developing a common metric in
+item response theory. *Applied Psychological Measurement, 7*(2),
+201-210. <https://doi.org/10.1177/014662168300700208>
+
+Haebara, T. (1980). Equating logistic ability scales by a weighted
+least squares method. *Japanese Psychological Research, 22*(3),
+144-149. <https://doi.org/10.4992/psycholres1954.22.144>
+
+Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, and
+linking: Methods and practices* (3rd ed.). Springer.
+<https://doi.org/10.1007/978-1-4939-0317-7>
+
+Kim, S., & Kolen, M. J. (2019). Application of IRT fixed parameter
+calibration to multiple-group test data. *Applied Measurement in
+Education, 32*(4), 310-324.
+<https://doi.org/10.1080/08957347.2019.1660344>
+
+Kang, T., & Petersen, N. S. (2012). Linking item parameters to a base
+scale. *Asia Pacific Education Review, 13*(2), 311-321.
+<https://doi.org/10.1007/s12564-011-9197-2>
+
+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>
+
+Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood
+estimation of item parameters: Application of an EM algorithm.
+*Psychometrika, 46*(4), 443-459.
+<https://doi.org/10.1007/BF02293801>
+
+American Educational Research Association, American Psychological
+Association, & National Council on Measurement in Education. (2014).
+*Standards for educational and psychological testing*. American
+Educational Research Association.
+
+## 11. Project Identification
 
 - Project Name: aFIPC
 - Repository URL: `https://github.com/ContextualWisdomLab/aFIPC`
 - Primary Contact: Seongho Bae
 - Date of Last Update: 2026-08-16
 
-## 11. Glossary / Acronyms
+## 12. Glossary / Acronyms
 
 - FIPC: Fixed Item Parameter Calibration
 - IPD: Item Parameter Drift
 - IRT: Item Response Theory
+- MML-EM: Marginal Maximum Likelihood via the EM algorithm

CLAUDE.md

@@ -88,8 +88,9 @@ score/theta outputs, returned as an R list.
 
 The linking contract (Kim, 2006): anchor items keep their old-form parameter
 values fixed during new-form calibration so the new form is calibrated
-directly onto the established scale. It is documented in
-`docs/fixed-parameter-item-calibration.md` and enforced by
+directly onto the established scale. That is FIPC, not a Stocking–Lord or
+Haebara transformation. It is documented in
+`docs/fixed-parameter-item-calibration.md` and `docs/adr/`, and enforced by
 `tests/testthat/test-fixed-parameter-calibration.R`.
 
 ## Key conventions
@@ -125,3 +126,5 @@ Summarized from `AGENTS.md` and `CONTRIBUTING.md`; read those for detail.
 - `CONTRIBUTING.md` — contribution process and verification baseline
 - `docs/operations/maintenance-runbook.md` — recurring maintainer operations
 - `docs/fixed-parameter-item-calibration.md` — calibration/linking basis
+- `docs/adr/` — FIPC, mirt MML-EM, and IPD/DIF decision records
+- `docs/papers/README.md` — verified source papers and DOIs

CONTRIBUTING.md

@@ -12,6 +12,9 @@ over feature velocity.
 2. Prefer small, auditable pull requests.
 3. Keep CI/security/docs healthy (`.github/workflows/`, `README.md`,
    `ARCHITECTURE.md`, `AGENTS.md`).
+4. Methodological decisions (linking contract, estimation engine) are
+   recorded in `docs/adr/`. Cite verified sources from
+   `docs/papers/README.md`; do not invent bibliographic records.
 
 ## Development Setup
 

README.md

@@ -1,55 +1,181 @@
 # aFIPC
 
-Automated Fixed Item Parameter Calibration (FIPC) for IRT test linking.
-
-This package contains the original graduate-school implementation used to
-produce accurate fixed-item linking results. The current maintenance goal is to
-preserve numerical behavior while modernizing repository operations
-(documentation, CI, and dependency hygiene).
-
-## What this repository contains
-
-- `R/aFIPC.R`: core `autoFIPC()` implementation
-- `DESCRIPTION`, `NAMESPACE`, `man/`: package metadata and generated docs
-- `packrat/`: historical dependency lock/vendor directory
-- `.github/workflows/`: CI/security automation
-
-## Development status
-
-- Algorithmic core is legacy but trusted for historical outputs.
-- Operational guardrails are now maintained via GitHub Actions and Dependabot.
-- Legacy `packrat` bootstrap is opt-in via `AFIPC_ENABLE_PACKRAT=true`.
-- Broken host-specific `packrat/lib-R` symlinks were removed for portable builds.
-- Architectural and agent operation docs are available in:
-  - `ARCHITECTURE.md`
-  - `AGENTS.md`
-  - `CLAUDE.md`
-  - `CONTRIBUTING.md`
-  - `.github/SECURITY.md`
-
-## Collaboration workflow
-
-- Pull request template: `.github/PULL_REQUEST_TEMPLATE.md`
-- Issue templates: `.github/ISSUE_TEMPLATE/`
-- Code ownership: `.github/CODEOWNERS`
-- Code quality checks: `.github/workflows/code-quality.yml`
-- Security checks (private-safe): `.github/workflows/security-audit.yml`
-- Secret-scan policy config: `.gitleaks.toml`
-- CodeRabbit command reference: `docs/coderabbit/review-commands.md`
-- Maintainer operations runbook: `docs/operations/maintenance-runbook.md`
-
-## Local package check
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ContextualWisdomLab/aFIPC)
+
+**Fixed-item IRT calibration for keeping test forms on a common score scale.**
+
+aFIPC automates fixed-item parameter calibration (FIPC) for linking and equating
+workflows. It helps psychometric teams carry anchor-item information from a
+reference form into calibration of a new form, inspect item-parameter drift, and
+obtain linked model/score artifacts without turning the repository into a
+general assessment platform.
+
+## When aFIPC fits
+
+Use aFIPC when you have a reference form, a newly administered form, and an
+explicitly reviewed set of common items whose parameters should anchor the
+linking design. The package owns the in-process calibration/linking workflow.
+Test delivery, source-system data collection, operational score policy, and
+downstream decision authority remain outside this repository.
+
+The numerical implementation is compatibility-sensitive. Changes to calibration
+behavior should be backed by regression evidence rather than incidental
+refactoring.
+
+## Core workflow
+
+1. Prepare old/reference-form and new-form response data, or compatible fitted
+   model objects.
+2. Identify the corresponding common-item names on both forms.
+3. Run `autoFIPC()` with the intended item model and explicit common-item
+   confirmation.
+4. Review convergence, item-parameter-drift evidence, and linked outputs before
+   downstream use.
+
+A non-interactive raw-data API shape is:
+
+```r
+result <- autoFIPC(
+  newformXData = new_form,
+  oldformYData = reference_form,
+  newformCommonItemNames = common_new,
+  oldformCommonItemNames = common_old,
+  newformBILOGprior = FALSE,
+  oldformBILOGprior = FALSE,
+  confirmCommonItems = TRUE
+)
+```
+
+The explicit BILOG-prior choices matter for the default 3PL path: leaving either
+choice as `NULL` can require interactive input when raw response data are fitted.
+If callers use already fitted compatible model objects, review the complete
+argument contract before omitting those raw-data choices.
+
+`autoFIPC()` returns the base-form, new-form, and linked-model artifacts as an R
+list. See `man/autoFIPC.Rd` for the complete argument contract.
+
+## Methodological boundary
+
+`autoFIPC()` implements FIPC: common items keep reference-form parameter values
+while the new form is calibrated onto that scale (Kim, 2006). This differs from
+separate calibration followed by Stocking-Lord or Haebara characteristic-curve
+transformations, and from concurrent calibration. aFIPC does not estimate
+Stocking-Lord or Haebara linking constants.
+
+The current estimation path delegates IRT estimation to `mirt` rather than
+owning an independent numerical IRT engine. The accepted method decisions are
+recorded in [the ADR index](docs/adr/README.md), and the verified APA records and
+DOIs are maintained in [the research index](docs/papers/README.md).
+
+Key sources include:
+
+- Kim, S. (2006). A comparative study of IRT fixed parameter calibration
+  methods. *Journal of Educational Measurement, 43*(4), 355-381.
+  <https://doi.org/10.1111/j.1745-3984.2006.00021.x>
+- 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>
+- Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood estimation of
+  item parameters: Application of an EM algorithm. *Psychometrika, 46*(4),
+  443-459. <https://doi.org/10.1007/BF02293801>
+
+Linking quality still depends on anchor quality, model fit, calibration
+assumptions, and the comparability of the forms being linked. Repository tests
+and cited methodology are implementation evidence; they do not make arbitrary
+forms automatically comparable.
+
+## Evaluate the current source
+
+This repository currently provides source rather than an immutable GitHub
+release. It also has a known GPL-family runtime blocker: `DESCRIPTION` imports
+`mirt`, and `rcmdcheck` does **not** install that dependency for the package under
+check. Therefore this README does not present a fresh `install.packages("mirt")`
+bootstrap as a commercially acceptable onboarding path.
+
+If you are maintaining the existing legacy development environment and its
+current dependency graph has already been provisioned for license-diligence or
+compatibility work, the repository check itself is:
 
 ```bash
 R_PROFILE_USER=/dev/null Rscript -e \
-'install.packages(c("rcmdcheck"), repos="https://cloud.r-project.org")'
+'install.packages("rcmdcheck", repos="https://cloud.r-project.org")'
+
 R_PROFILE_USER=/dev/null Rscript -e \
 'rcmdcheck::rcmdcheck(args = c("--no-manual", "--as-cran"), error_on = "warning")'
 ```
 
-## Maintenance policy
+This is **not** a clean commercial-install recipe: `rcmdcheck` expects the
+package's declared runtime dependencies, including the currently disallowed
+`mirt`, to already exist. A commercially compatible clean setup is blocked until
+issue #320 replaces/removes that runtime path and the final package graph is
+revalidated.
+
+The historical `packrat/` tree is retained for compatibility archaeology. Its
+bootstrap is opt-in via `AFIPC_ENABLE_PACKRAT=true` and should not be treated as
+the preferred dependency workflow.
+
+## Architecture and responsibility
+
+The runtime is single-process and fileless: callers provide in-memory R
+data/model objects and receive R model artifacts. `R/aFIPC.R` owns the main
+fixed-item linking workflow, while `R/surveyFA.R` contains supporting analytical
+routines. Package metadata and generated reference docs live in `DESCRIPTION`,
+`NAMESPACE`, and `man/`.
+
+The current calibration engine calls the external `mirt` package for IRT
+estimation and parameter/model operations. That dependency is a material runtime
+boundary, not an implementation detail that the repository license can override.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the component map and maintenance
+boundaries.
+
+## Quality and change control
+
+Repository automation covers R package checks, code/document quality,
+workflow/security auditing, dependency review where the platform supports it,
+and supply-chain posture. Before modifying estimation/linking logic, read
+[CONTRIBUTING.md](CONTRIBUTING.md) and preserve the documented regression and
+review discipline.
+
+Current source metadata is `0.1.0`; the repository does not currently publish
+GitHub Releases. A source version or passing development check is therefore not
+presented as an immutable supported release.
+
+## Commercial licensing status
+
+**Not currently cleared for ContextualWisdomLab commercial
+intake/distribution.**
+
+`DESCRIPTION` presently declares `GPL-3 | file LICENSE`, while the runtime
+directly imports `mirt`, whose current CRAN distribution is GPL-family licensed.
+ContextualWisdomLab's commercial intake policy does not accept GPL/LGPL/AGPL
+family software as the normal dependency baseline. The repository-authored
+source grant and third-party runtime obligation are separate questions; neither
+can be made policy-compliant by README wording alone.
+
+Issue #320 owns the required source-provenance/relicensing review and replacement
+of the GPL-family runtime path while preserving the actual fixed-item
+calibration/linking estimand and regression behavior. Until that work is
+integrated and verified, do not present this repository as Apache-2.0/MIT
+cleared or commercially policy-compliant.
+
+## Documentation
+
+- [Public documentation home](docs/index.md) - product scope, workflow,
+  architecture, and change-control entry point.
+- [FIPC linking contract](docs/fixed-parameter-item-calibration.md) - what is
+  fixed, what is estimated, and how the linked scale is defined.
+- [Architecture decisions](docs/adr/README.md) - FIPC and estimation decisions.
+- [Research sources](docs/papers/README.md) - verified methodological references
+  and DOIs.
+- [Architecture](ARCHITECTURE.md) - component and responsibility boundaries.
+- [Generated R reference](man/autoFIPC.Rd) - `autoFIPC()` API contract.
+- [Contributing](CONTRIBUTING.md) - contributor workflow and verification
+  expectations.
+- [.github/SECURITY.md](.github/SECURITY.md) - vulnerability-reporting guidance.
+- [Ask DeepWiki](https://deepwiki.com/ContextualWisdomLab/aFIPC) -
+  repository-aware navigation.
 
-- Prefer preserving equation/calibration behavior over refactoring.
-- Avoid silent behavioral changes in `autoFIPC()` without explicit regression
-  evidence.
-- Keep CI green on supported runners and keep Actions pinned/updated.
+For scientific or operational changes, open an issue or pull request with the
+exact design assumptions, affected calibration behavior, and reproducible
+verification evidence.