From d6ab9d776143cebb73ea2d47f348c1575fcd6e84 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 11:02:05 +0900 Subject: [PATCH 1/2] docs: add DeepWiki badge and product-facing overview --- README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7e5816f2..bc4387c6 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,8 @@ # aFIPC -Automated Fixed Item Parameter Calibration (FIPC) for IRT test linking. +[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ContextualWisdomLab/aFIPC) -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). +Automated Fixed Item Parameter Calibration (FIPC) for IRT test linking and equating. aFIPC helps psychometric teams preserve score-scale continuity across test forms by fixing anchor-item parameters while estimating parameters for newly administered items. ## What this repository contains @@ -13,11 +10,12 @@ preserve numerical behavior while modernizing repository operations - `DESCRIPTION`, `NAMESPACE`, `man/`: package metadata and generated docs - `packrat/`: historical dependency lock/vendor directory - `.github/workflows/`: CI/security automation +- `docs/index.md`: product, architecture, onboarding, and release-facing documentation ## Development status -- Algorithmic core is legacy but trusted for historical outputs. -- Operational guardrails are now maintained via GitHub Actions and Dependabot. +- Algorithmic behavior is preserved for compatibility with established linking outputs. +- Operational guardrails are 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: @@ -50,6 +48,5 @@ R_PROFILE_USER=/dev/null Rscript -e \ ## Maintenance policy - Prefer preserving equation/calibration behavior over refactoring. -- Avoid silent behavioral changes in `autoFIPC()` without explicit regression - evidence. +- Avoid silent behavioral changes in `autoFIPC()` without explicit regression evidence. - Keep CI green on supported runners and keep Actions pinned/updated. From 066150a38b3fc443a69a1144c0e38c88fc906482 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 11:02:22 +0900 Subject: [PATCH 2/2] docs: add Pages-ready product landing page --- docs/index.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..1f6fbe1d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,50 @@ +# aFIPC + +Automated Fixed Item Parameter Calibration for item-response-theory linking and equating. + +## Product responsibility + +aFIPC preserves a common measurement scale across test forms by combining anchor-item parameters from a reference form with calibration of newly administered items. It is intended for psychometric workflows where score comparability across administrations matters and fixed-item linking is the chosen design. + +## Core workflow + +1. Prepare reference-form and new-form response data with a stable set of common items. +2. Fit or supply the reference-form item parameters used as linking anchors. +3. Run `autoFIPC()` to construct the fixed-item calibration workflow for the new form. +4. Review model diagnostics and linking outputs before downstream score reporting or operational use. + +## Architecture + +The repository is an R package with a focused calibration core: + +- `R/aFIPC.R` contains the main fixed-item linking workflow. +- `R/surveyFA.R` contains supporting analytical routines used by the package. +- `DESCRIPTION`, `NAMESPACE`, and `man/` define package metadata and generated reference documentation. +- `ARCHITECTURE.md` documents structural boundaries and maintenance constraints. +- `.github/workflows/` provides continuous-integration and security checks. + +The package keeps established numerical behavior as a compatibility constraint; behavioral changes should be supported by regression evidence rather than incidental refactoring. + +## Onboarding + +Clone the repository, use a current R toolchain, and run the package checks before changing calibration behavior: + +```bash +R_PROFILE_USER=/dev/null Rscript -e \ +'install.packages(c("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")' +``` + +For contributor expectations and architectural context, read `CONTRIBUTING.md` and `ARCHITECTURE.md` before modifying estimation or linking logic. + +## Releases and change control + +The repository currently does not publish GitHub Releases. Until a tagged release is available, consumers should pin an explicitly tested commit or package build and review the repository history for behavioral changes. Calibration changes should preserve reproducibility and be accompanied by test evidence. + +## Documentation and support + +- Repository README: concise product and contributor entry point. +- `ARCHITECTURE.md`: package boundaries and design context. +- `man/`: generated R reference documentation. +- [Ask DeepWiki](https://deepwiki.com/ContextualWisdomLab/aFIPC): repository-aware documentation and code navigation.