Readable handbook for the full project state.

Modernized codebase from the PhD thesis "A Method of Program Understanding using Constraint Satisfaction" (Steven Woods, University of Waterloo, CS-96-33).

Originally developed in Allegro Common Lisp on SPARC, renovated for SBCL on modern hardware.

What This Is

A constraint satisfaction approach to automated program understanding. Given a program's abstract syntax, the system matches it against a library of programming plans (templates) using CSP techniques to identify algorithmic patterns.

Three CSP solving strategies are implemented and compared:

• MAP-CSP (adt): Direct CSP matching with backtracking, forward checking, and dynamic rearrangement
• Memory-CSP (memory-search): Two-phase approach using a memory of previously solved problems to guide search
• Quilici Search: Memory-based retrieval with similarity metrics

Project Goal

The primary goal is not just to make the Lisp code run on modern hardware. It is to restore an integrated constraint-solver baseline that:

1. reproduces the PhD-reported results,
2. covers the other historical domains and reported result families preserved

in the repo and archive intake, and

1. converges toward one gold-standard code line that can stand in for the

historical solver lineage with any remaining deltas explained.

Current focus after 1.0.0: keep the supported PhD-result validation path green, use the integrated baseline as the stable reference point, and make the next major effort the ingestion, de-duplication, and categorization of newly found relevant material. See RENOVATION.md for the active roadmap, VALIDATION-MATRIX.md for the current domain/result coverage map, REPOSITORY-STATUS.md for the repo-wide integration/testing/publication status table, REPOSITORY-STRUCTURE-REVIEW.md for the filesystem clarity review, and docs/release-dashboard.html for the visual release dashboard. A full generated handbook now lives at docs/project-handbook.html, with the public readable copy at <https://sgwoods.github.io/public/phd-renovation-handbook.html>. The same source data and doc-refresh build now drive the handbook, dashboard, and public-facing PhD project page so those views stay in sync. The thesis itself is available from the project home surfaces in both docs/phd-renovation-thesis.pdf and docs/phd-renovation-thesis.ps form, with the canonical source PDF preserved under data/thesis/.

Project Structure

csp/                        Base CSP solver (backtracking, AC-3, queens, ADT, MPR)
qcsp3/                      Extended solver (memory-CSP, GSAT, Quilici search)
qcsp-may29-1996/            Historical snapshot (May 1996, includes embedded batch data)
qcsp-alex-sep16-1997/       Historical snapshot (Sep 1997, with extended adt)
data/                       Consolidated data directory (see data/README.md)
  sparc-archive/            Original SPARC archive listings and thesis-era data
  acl-experiments/          Original ACL experiment results (ij2/ij3/ij4)
  csp-batch/                Earliest batch experiments (T1-T6, 1993-1994)
  csp-adt-batch/            ADT domain batch experiments (ij1-ij4)
  motors-releases/          MOTORS solver releases (.tar.Z, 1993)
  motors-backups/           MOTORS solver backups (.zoo, 1994)
  thesis/                   Canonical PhD thesis source PDF
Q-Batch-SBCL/               Replicated experiments (SBCL, M4 Mac)
  Graph/                    4-way comparison plots (ACL vs qcsp3 vs alex vs may29)
incoming/                   Single intake bucket for newly found relevant material
tests/                      FiveAM test suites
src/                        Entry point

Where To Look

• qcsp3/ is the primary codebase for the supported thesis-validation

baseline and the leading candidate for the future gold-standard integrated solver; csp/, qcsp-may29-1996/, and qcsp-alex-sep16-1997/ are the comparison snapshots.

• tests/ is the authoritative validation surface. It contains the Four

FiveAM suites, the asserted AO runner, and the artifact/thesis-result validation scripts that CI uses. The AO runner now covers the bounded M1 AO surface: qcsp3/may29 cases 1-3 plus wrappers, and the alex revise baseline.

• Q-Batch-SBCL/ is the runnable SBCL experiment workspace. It holds the

modern experiment drivers, generated run directories, and comparison plots.

• data/ holds preserved ACL/SPARC-era baselines and archive material.
• data/thesis/ holds the canonical thesis PDF; the docs/status build exports

public-facing docs/phd-renovation-thesis.pdf and docs/phd-renovation-thesis.ps copies from it.

• incoming/ is the first stop for newly found relevant code, data,

publications, or experiment artifacts before review and promotion. Dump names are fine; review can normalize the folder label later if the contents reveal a better date/source name.

• historical finds/ is archive intake and provenance work, not supported

baseline code.

• Root run-test4*.lisp, run-csp-tests.lisp, and renovate.lisp are

manual compatibility helpers, not the primary supported workflow.

• VALIDATION-MATRIX.md summarizes which historical domains and result

families are executable now, integrity-checkable now, or still reference-only.

• REPOSITORY-STATUS.md answers the broader repo-wide question: what is

indexed, integrated, tested, and publication-validated.

• RELEASE-1.0-CHECKLIST.md is the concrete release-hardening punch list for

the first 1.0.0 tag.

• RELEASE-1.0.0-NOTES.md is the working draft of the first release notes.
• HANOI-4-STATUS.md records the current bounded position on the Hanoi-4

lane: documented for 1.0, behaviorally unresolved as a 2.0 goal.

• DOCS-COVERAGE-REVIEW.md records what parts of the repo are now well

documented, what still feels thin, and where the next docs passes should go.

• WORKFLOWS.md maps the primary supported operator workflows and the

secondary/manual ones.

• docs/project-handbook.html is the full generated human-readable handbook

that gathers the major status, roadmap, workflow, and architecture docs into one indexed page.

• docs/README.md explains which files under docs/ are authoritative source

data versus generated outputs.

• MANUAL-HELPERS.md explains the repo-root helper scripts and how they

relate to the supported operator flow.

• tools/README.md explains the maintained generators that keep the dashboard,

handbook, public page, and status manifest synchronized.

• REPOSITORY-STRUCTURE-REVIEW.md classifies the repo layout into supported

systems, result archives, experiment workspaces, and archive-only material.

• DUPLICATES-REVIEW.md records which reviewed historical overlaps are true

duplicates versus which still carry archive/provenance value.

• incoming/README.md and incoming/INDEX.md define and track the intake flow

for future finds.

• historical finds/README.md explains the reviewed archive/recovery lane and

how it differs from both incoming/ and the supported baseline.

• qcsp-alex-sep16-1997/testdata/Results/README.md and

qcsp-alex-sep16-1997/testdata/Results-Loop/README.md clarify the deeper preserved Alex result families.

• historical finds/Refine/README.md, historical finds/Unravel/README.md,

and historical finds/Unravel-changes/README.md provide local guidance for the archive-only recovered tooling/context trees.

ASDF Systems

Quick Start

Requires SBCL and Quicklisp.

# Interactive REPL
sbcl --load "src/main.lisp"

# Run all FiveAM test suites (CSP, QCSP3, May29, Alex)
sbcl --non-interactive --load "tests/run.lisp"

# Run asserted AO regression coverage
sbcl --non-interactive --load "tests/ao-run.lisp"

# Run individual suites
sbcl --non-interactive --load "tests/csp-suite.lisp"
sbcl --non-interactive --load "tests/qcsp3-suite.lisp"
sbcl --non-interactive --load "tests/may29-suite.lisp"
sbcl --non-interactive --load "tests/alex-suite.lisp"

# Run the validation spine used by CI
bash tests/validate-artifacts.sh
bash tests/validate-dashboard.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-adt-batch.sh
bash tests/validate-csp-batch.sh
bash tests/validate-ao.sh

# Run legacy/manual AO harnesses
sbcl --non-interactive --load "run-test4.lisp"
sbcl --non-interactive --load "run-test4-may29.lisp"
sbcl --non-interactive --load "run-test4-alex.lisp"

# Try it interactively
# (qc 4)              ;; 4-Queens
# (qc 8)              ;; 8-Queens
# (adt)               ;; ADT pattern recognition
# (memory-search)     ;; Two-phase memory-based search

Experiments

Three experiment series evaluate CSP search efficiency under increasing noise (50-1000 extraneous program statements):

Each series: 20 noise levels x 10 random seeds = 200 runs per snapshot.

Running experiments

# qcsp3 (primary system)
bash Q-Batch-SBCL/ij2.sh && bash Q-Batch-SBCL/ij3.sh && bash Q-Batch-SBCL/ij4.sh

# Historical snapshots
bash Q-Batch-SBCL/run-alex-all.sh      # alex (Sep 1997)
bash Q-Batch-SBCL/run-may29-all.sh     # may29 (May 1996)

Generating comparison plots

python3 Q-Batch-SBCL/Graph/compare-all-overlay.py    # 4-way overlay plots (uses data/acl-experiments/Graph)

Results

The supported SBCL baseline preserves the published ACL/SPARC experimental story for ij2, ij3, and ij4: the regenerated CI curves stay highly correlated with the thesis-era ACL curves, preserve the same efficiency ordering, and remain within stable per-series ratio bands. Exact magnitudes are not identical across platforms, so the repo validates historical trend preservation rather than claiming point-for-point statistical identity.

The older ADT ij1-ij4 archive family is now integrity-checkable through tests/validate-adt-batch.sh, which validates the preserved raw file grids and historical CI summaries without claiming a full modern rerun path.

The earliest DREV-era T1-T6 family is now integrity-checkable through tests/validate-csp-batch.sh, which validates the preserved summary layer in data/csp-save-results/ against the historical batch tree and its known archive quirks.

Key findings:

• Direct CSP matching (ij4) is 10-100x more efficient than the two-phase memory approach (ij2) in constraint checks, but the memory approach provides adaptability benefits not captured by this metric.
• The alex snapshot shows significantly higher TCC in ij4 because its

ts-matches-type logic was simplified relative to the earlier snapshots; the dormant DFA options may be the missing compensating mechanism.

Plots are in Q-Batch-SBCL/Graph/compare-*-overlay.png.

Directory guides:

• csp/README.md
• csp/ADT-Random/README.md
• csp/MPR-Random/README.md
• csp/MPR-Situation/README.md
• qcsp3/README.md
• qcsp3/extras/README.md
• qcsp3/ADT-Batch/README.md
• qcsp3/ADT-Random/README.md
• qcsp3/ADT-Situation/README.md
• qcsp3/MPR-Random/README.md
• qcsp3/MPR-Situation/README.md
• src/README.md
• Q-Batch-SBCL/README.md
• Q-Batch-SBCL/Graph/README.md
• tests/README.md
• qcsp-may29-1996/extras/README.md
• qcsp-may29-1996/ADT-Random/README.md
• qcsp-may29-1996/ADT-Situation/README.md
• qcsp-may29-1996/ADT-SituationMar96/README.md
• qcsp-may29-1996/MPR-Random/README.md
• qcsp-may29-1996/MPR-Situation/README.md
• qcsp-alex-sep16-1997/MyBatch/README.md
• qcsp-alex-sep16-1997/ADT-Random/README.md
• qcsp-alex-sep16-1997/ADT-Situation/README.md
• qcsp-alex-sep16-1997/MPR-Random/README.md
• qcsp-alex-sep16-1997/MPR-Situation/README.md
• qcsp-alex-sep16-1997/testdata/Results/README.md
• qcsp-alex-sep16-1997/testdata/Results-Loop/README.md
• WORKFLOWS.md
• MANUAL-HELPERS.md
• docs/README.md
• tools/README.md
• data/README.md
• incoming/README.md
• historical finds/README.md
• historical finds/Refine/README.md
• historical finds/Unravel/README.md
• historical finds/Unravel-changes/README.md
• REPOSITORY-STATUS.md
• REPOSITORY-STRUCTURE-REVIEW.md
• DOCS-COVERAGE-REVIEW.md
• DUPLICATES-REVIEW.md
• ADT-BATCH-INTEGRATION.md

License

Academic research code. See data/thesis/ for the thesis.

This file answers a broader question than VALIDATION-MATRIX.md:

Is the entire repository indexed and, where practical, integrated, tested, and validated against published or historically reported results?

Short answer: not entirely yet.

• The primary solver line, reference snapshots, main thesis-result pipeline,

bounded AO baseline, and several preserved result families are now indexed and either executable or integrity-checkable.

• Large portions of the archive are documented and classified, but are not yet

part of the supported integrated line.

• Some historical systems, datasets, and toolchains are preserved mainly for

provenance, recovery, or context rather than active validation.

Use this artifact as the repo-wide counterpart to VALIDATION-MATRIX.md. For reviewed duplicate and redundancy decisions, see DUPLICATES-REVIEW.md. For the practical operator view of "what do I run?", see WORKFLOWS.md. For the repo-root helper scripts specifically, see MANUAL-HELPERS.md. For the documentation-focused coverage read, see DOCS-COVERAGE-REVIEW.md. For the current bounded Hanoi-4 position, see HANOI-4-STATUS.md. For the concrete 1.0.0 release gate, see RELEASE-1.0-CHECKLIST.md.

Status Key

• Indexed: documented well enough that its role in the repo is understood.
• Integrated: part of the supported solver story rather than just preserved.
• Automated: covered by CI or a repeatable validation script.
• Publication / report validation: tied directly to thesis or historically

reported results, either executable or integrity-checkable.

Executive Read

Repository-Wide Coverage Table

What This Means

The repository now has three broad zones:

1. Supported integrated baseline

qcsp3/, the validation spine in tests/, the modern experiment workspace in Q-Batch-SBCL/, and the thesis-era ACL baselines under data/.

1. Reference and integrity-check layers

Historical snapshots and preserved result families that are documented and checked, but not yet folded into one executable gold-standard line.

1. Archive, recovery, and context material

Recovered historical finds, compressed legacy archives, and missing-domain trackers that matter to the long-term story but are not yet integrated.

1. Incoming review queue

Newly found relevant material should land in incoming/ first, then be reviewed and promoted into one of the three zones above.

1. Deferred research-readiness lanes

Topics like Hanoi-4 that are important enough to track explicitly, but whose current 1.0 requirement is documentation and bounded scope rather than full behavioral closure.

Deliberate Mainline Priority

The current post-1.0.0 mainline priority is intake hardening and release maintenance.

That means the current recommended order is:

1. keep the supported validation spine green and the repo status artifacts

current,

1. make incoming/ review, de-duplication, and categorization the next major

operational lane,

1. target 1.0.1 for remaining STYLE-WARNING cleanup outside the supported

release gate,

1. treat ADT batch as a snapshot-specific preserved family rather than an

active integration obligation,

1. keep terrain as the major deferred recovery lane, and
2. treat Hanoi-4 as a documented 1.x lane and a 2.0

research/repeatability goal.

The current ADT batch note lives in ADT-BATCH-INTEGRATION.md. Current recommendation: keep the preserved wrapper mapping and bridge probes as historical explanation, but do not require the maintained integrated line to absorb the family.

Maintenance Rule

Keep this file in sync whenever one of these changes happens:

1. a directory or result family moves from provenance-only to

integrity-checkable or executable,

1. a new top-level archive or workspace is added,
2. a previously manual workflow becomes part of the supported line, or
3. a result family becomes publication-validated in a stronger way than before.

This file tracks the historical domains and result families that matter to the project's primary goal:

1. validate the integrated solver against the PhD-reported results,
2. validate it against other historically reported domains/results, and
3. converge on one gold-standard code line that can cover that validated scope.

qcsp3/ is currently the leading candidate for that gold-standard line. It has now cleared Milestone M1, but it has not yet earned that status across the full historical surface.

First Integration Milestone

The first explicit gate for qcsp3/ is:

Milestone M1: integrated validated baseline

To satisfy M1, qcsp3/ must:

1. stay green across the current validation spine,
2. remain the default executable path for the supported PhD ij2/ij3/ij4

story,

1. include the asserted AO baseline as part of the supported integrated line,
2. carry an explicit documented relationship to the preserved ff* family,

even if that family is still integrity-checkable rather than rerunnable through qcsp3/, and

1. document any remaining meaningful deltas versus the historical snapshots.

This is the first practical step toward one gold-standard code line. M1 is now accepted, but it is not the final "everything historical is unified" finish line.

The current delta ledger for this milestone lives in INTEGRATION-DELTAS.md. The short gate summary for this milestone lives in M1-READINESS.md. The current ADT batch investigation note lives in ADT-BATCH-INTEGRATION.md.

Status Key

• Executable now: we have a supported runnable validation path today.
• Integrity-checkable now: the preserved artifacts can be checked or compared

reliably, even if we do not yet have a clean modern rerun path.

• Provenance-only for now: the family is historically meaningful, but the

executable or integrity story is not yet strong enough.

Current Matrix

Immediate Priorities

1. Keep the currently executable PhD-result path green.
2. Use the current matrix to guide intake review, de-duplication, and

categorization as new material lands in incoming/.

1. Treat ADT batch as an explained snapshot-specific family unless a future

project phase explicitly chooses to emulate its older noise semantics.

1. Keep the supported validation spine warning-clean and treat any new log

noise in that path as a regression signal.

1. As new material lands in incoming/, classify it deliberately as

executable, integrity-checkable, provenance-only, or duplicate before promoting it into the main repo story.

1. Use 1.0.1 for remaining STYLE-WARNING cleanup outside the supported

release gate rather than letting that noise blur intake or release work.

1. Move the next clearly supported family or workflow only when it helps the

post-1.0.0 integrated line more than it increases maintenance surface.

1. Treat Hanoi-4 as explicitly bounded for 1.x: maintain a clear status

record, but defer full behavior/repeatability understanding to 2.0.

This file is the concrete punch list for the first 1.0.0 release.

It turns the current roadmap into a release gate we can actually close.

What 1.0.0 Means

1.0.0 does not mean every preserved historical family is fully rerunnable through one code path.

It means:

1. the supported thesis-result baseline is executable from a fresh checkout,
2. the supported integrated solver story is honest and bounded,
3. the major preserved historical families are either executable,

integrity-checkable, or explicitly deferred,

1. the repo/public documentation accurately describes that scope, and
2. release notes can explain remaining deltas as intentional rather than

accidental.

In Scope For 1.0.0

• qcsp3/ as the operational center of the supported integrated line
• supported thesis ij2 / ij3 / ij4 validation path
• bounded AO baseline
• ff* integrity/provenance relationship
• ADT batch and DREV-era T1-T6 as preserved integrity-checkable families
• clear status artifacts, handbook, dashboard, and public project page
• explicit deferred-lane documentation for terrain and Hanoi-4

Explicitly Out Of Scope For 1.0.0

• full terrain-domain recovery
• full Hanoi-4 behavior/repeatability closure
• forcing snapshot-specific preserved families into qcsp3/ when they are

better treated as documented archives

• broader post-M1 research experiments such as alex DFA-option exploration as

a release blocker

Required Validation Gate

These must pass for a 1.0.0 release candidate:

sbcl --non-interactive --load "tests/run.lisp"
bash tests/validate-artifacts.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-adt-batch.sh
bash tests/validate-csp-batch.sh
bash tests/validate-ao.sh
bash tests/validate-dashboard.sh

Required Status / Docs Conditions

• [x] README.md, RENOVATION.md, VALIDATION-MATRIX.md, and

REPOSITORY-STATUS.md agree on current scope

• [x] M1-READINESS.md, INTEGRATION-DELTAS.md, and

HANOI-4-STATUS.md reflect current accepted boundaries

• [x] docs/release-dashboard-data.json reflects the active release focus
• [x] generated outputs are current:

docs/release-dashboard.html, docs/project-handbook.html, docs/public-phd-renovation.html, docs/public-phd-renovation-handbook.html, docs/public-status-phd-renovation.json

• [x] public-facing wording matches repo-local wording

Required Scope Conditions

• [x] supported executable families are clearly identified
• [x] integrity-checkable preserved families are clearly identified
• [x] snapshot-specific preserved families are clearly identified
• [x] deferred lanes are clearly identified
• [x] no hidden 1.0 blockers remain in project docs

Release Notes Must State

• what the integrated line now guarantees
• what validation is continuously exercised
• which historical families are executable now
• which historical families are integrity-checkable only
• which historically important lanes are deferred
• which meaningful deltas remain documented

Current draft:

• RELEASE-1.0.0-NOTES.md

Tag / Release Process

1. Regenerate the status/docs outputs.
2. Run the full validation gate.
3. Confirm the branch is clean.
4. Draft release notes from this checklist and the current roadmap.
5. Tag the release.
6. Push the tag and any synced public outputs.

Post-Release Reminder

Target 1.0.1 to reduce the remaining STYLE-WARNING noise that still appears outside the supported release gate, especially older gsat lexical-special warnings and legacy helper-path warnings such as the compile-all reference.

Current Best Read

As of March 22, 2026, the project looks close enough to 1.0.0 that the main remaining work is release hardening, not broad new solver expansion.

The most likely remaining pre-1.0 work is:

1. final selective docstrings and operator-facing cleanup,
2. drafting the actual 1.0.0 release notes from the now-stable scope,
3. keeping docs/status/public outputs synchronized,
4. keeping the validation gate green,
5. and making sure deferred lanes like terrain and Hanoi-4 stay explicit

rather than quietly becoming implied blockers.

Summary

1.0.0 marks the first stable integrated release of the PhD renovation project.

This release establishes a clear, reproducible thesis-result baseline on modern SBCL, classifies the major preserved historical families honestly, and ships with synchronized status, handbook, dashboard, and public project pages.

What This Release Guarantees

• qcsp3/ is the operational center of the supported integrated solver line.
• The supported thesis ij2 / ij3 / ij4 result story is executable from a

fresh checkout.

• The bounded AO / test4 baseline is asserted rather than smoke-only.
• The older ff*, ADT batch, and DREV-era T1-T6 families are no longer

vague archive material; they are documented and integrity-checkable where appropriate.

• The project’s supported scope, deferred lanes, and historical deltas are

documented explicitly rather than left as implicit lore.

Validation Gate

1.0.0 is backed by the supported validation spine:

• tests/run.lisp
• tests/validate-artifacts.sh
• tests/validate-ff-provenance.sh
• tests/validate-adt-batch.sh
• tests/validate-csp-batch.sh
• tests/validate-ao.sh
• tests/validate-dashboard.sh

Historical Coverage

Executable now

• core queens regressions across the maintained snapshots
• confused-queens deterministic metrics
• bounded AO baseline
• PhD ij2 / ij3 / ij4 trend-validation path
• solver-level MPR regression surface

Integrity-checkable now

• ff1 / ff2 / ff3
• early exp-1 / exp-2 / exp-3 crosswalked result families
• ADT batch archive (ij1-ij4)
• earliest DREV-era T1-T6 family

Snapshot-specific or deferred

• ADT batch remains a documented snapshot-specific family rather than a

required qcsp3 reproduction target

• terrain remains a deferred recovery lane
• Hanoi-4 is documented for 1.0, with full behavioral and repeatability

understanding deferred to 2.0

• alex DFA-option behavior remains a research-readiness lane rather than a

1.0 blocker

Important Boundaries

1.0.0 does not claim:

• complete recovery of all historical domains,
• full rerun support for every preserved archive family,
• or final closure on harder post-thesis research questions like terrain or

Hanoi-4 repeatability.

Instead, it claims a trustworthy supported baseline with explicit boundaries.

Meaningful Remaining Deltas

• alex ij4 still diverges in the documented way tied to its simplified

ts-matches-type behavior

• ADT batch remains preserved and investigated, but not absorbed into the

integrated line

• some legacy STYLE-WARNING noise remains outside the main release gate

Documentation And Operator Improvements

This release also establishes:

• a generated project handbook,
• a generated release dashboard,
• a generated public project page and public handbook,
• a synchronized public status manifest,
• stronger local README coverage across the active solver line and historical

snapshots,

• and a first-class release checklist for future tags.

Suggested Announcement Line

1.0.0 is the first release where the renovated solver line, thesis-result validation path, preserved historical family classification, and public-facing status/documentation story all line up cleanly enough to treat the project as stable and trustworthy to build on.

This file records the repo's current position on Hanoi-4.

It exists to keep the plan honest: Hanoi-4 is now treated as a documented post-1.0 research/repeatability lane rather than an implicit blocker for the first gold-standard integrated solver release.

Current Read

Short answer: Hanoi-4 is not currently an indexed, validated, or integrated result family in this repository.

As of March 22, 2026:

• no tracked Hanoi-4 experiment family is indexed in the main validation

matrix,

• no executable Hanoi-4 validation harness is part of the supported gate,
• and no repo-local preserved artifact set has yet been promoted into the

supported or integrity-checkable surface.

That does not make Hanoi-4 unimportant. It means the repo should describe the gap clearly instead of letting it act as an undefined 1.0 obligation.

1.0 Position

For the 1.0 integrated-line goal, the requirement is:

1. a clear statement of the current Hanoi-4 situation,
2. a clear record of any known or newly ingested Hanoi-4 artifacts,
3. a clear note that previous work may indicate repeatability variation, if

and when the supporting references are actually ingested and indexed, and

1. an explicit statement that full behavioral understanding is deferred.

So 1.0 requires clarity and bounded scope, not a complete Hanoi-4 repeatability solution.

2.0 Position

For the eventual 2.0 research-readiness goal, the requirement becomes:

1. identify and ingest the historical Hanoi-4 code, data, and result

artifacts,

1. index any publications, notes, or result summaries that discuss the domain,
2. determine whether the historical Hanoi-4 results are stably repeatable or

whether they vary materially across runs, environments, or solver variants,

1. explain any observed repeatability variation with evidence, and
2. decide whether Hanoi-4 should become executable, integrity-checkable, or

remain a documented research-only family.

Future Research References

The future Hanoi-4 lane should not start from scratch. Once actual Hanoi-4 artifacts are ingested, this lane should explicitly review later planning/encoding work that may suggest better problem formulations than the historical 1998 framing.

Initial seeded reference:

• Ruben Martins and Ines Lynce, *Effective CNF Encodings for the Towers of

Hanoi* (LPAR 2008 / EasyChair proceedings). URL: <https://sat.inesc-id.pt/~ines/publications/lpar08-sp.pdf> Why it matters here:

• it surveys stronger SAT/CNF encodings for Towers of Hanoi,
• it encodes structural properties like recursive move sequence, disk parity,

and disk cycle behavior,

• and it gives us a concrete later-era reference point for thinking about

hierarchical setup, problem encoding choices, and whether repeatability questions may partly be encoding questions rather than only solver questions.

This does not mean the repo is adopting SAT-based Hanoi work as part of the current integrated Lisp baseline. It means future Hanoi-4 analysis should be informed by later literature instead of treating the 1998 state as the only conceptual frame.

Current Artifact / Reference Status

Intake Rule

When Hanoi-4 materials are found:

1. land them in incoming/ first,
2. record them in incoming/INDEX.md,
3. review whether they are code, data, results, notes, or duplicate/archive

overlap,

1. update this file with the concrete artifact and reference inventory, and
2. only then decide whether they belong in the integrated line, a preserved

archive lane, or a research-only lane.

Planning Rule

Until a real Hanoi-4 artifact/reference set is ingested and reviewed, the project should not treat Hanoi-4 as a hidden blocker for 1.0.

It should treat Hanoi-4 as:

• documented for 1.0, and
• behaviorally unresolved for 2.0.

This file answers one narrow question:

What still matters for Milestone M1, and are any remaining non-terrain historical families still blocking it?

Short answer: no additional non-terrain family is currently an undisclosed M1 blocker. The only explicitly blocked major historical lane remains the terrain domain, and that is outside M1 by design.

Project decision as of March 21, 2026: Milestone M1 is accepted.

M1 Gate Checklist

Non-Blocking For M1

These matter historically, but they are not first-gate blockers for M1:

Explicitly Outside M1

Practical M1 Reading

M1 is ready when we can say all of the following with a straight face:

1. qcsp3/ is the operational center of the supported thesis-result story.
2. The current validation spine stays green from a fresh checkout.
3. AO support is asserted and honestly bounded rather than hand-waved.
4. ff* stays connected to the integrated line as a checked preserved family.
5. The remaining archive-heavy families are explicitly post-M1 rather than

silently missing.

That means the question is no longer "what other non-terrain archive family must be pulled in before M1?" M1 has been accepted, and the active question is now "what documentation and operator-facing cleanup best prepares the repo for the next integration step?"

This file records the remaining meaningful differences between qcsp3/ and the historical reference snapshots that matter for Milestone M1 and the eventual gold-standard integrated solver line.

It is not a changelog of every historical quirk. It is the short list of currently relevant deltas that future work should either:

1. accept and document,
2. reduce and validate, or
3. treat as an explicit blocker.

How To Read This

• Accept for M1: documented and bounded; not a blocker for the first

integrated validated baseline.

• Reduce after M1: real gap, but not a first-gate blocker once the boundary

is explicit.

• Blocker outside M1: important, but outside the first integrated-baseline

target because artifacts or coverage are still missing.

Current Delta Table

What M1 Now Means In Practice

Milestone M1 is satisfied when:

1. qcsp3/ remains the operational center of the supported thesis-result path,
2. the current validation spine stays green,
3. AO baseline support is asserted and honestly bounded,
4. the ff* family remains explicitly connected to the integrated line even if

it is still integrity-check-only, and

1. the deltas above remain documented instead of being implicit lore.

So M1 does not mean "all historical families are unified already." It means the repo has crossed from "best-supported candidate" to "first explicitly integrated validated line."

For the short operational answer to "what still blocks M1 right now?", see M1-READINESS.md.

Onboarding guide for AI assistants and developers working on this project.

What This Project Is

A 1990s PhD research codebase (Common Lisp) that solves program understanding as a constraint satisfaction problem. Given a program's abstract syntax, the solver matches it against a library of programming plans (templates) to identify algorithmic patterns like sorting, searching, or data structure operations.

The codebase was originally written in Allegro Common Lisp on SPARC/Solaris (1993-1997) and has been renovated to run on SBCL (Steel Bank Common Lisp) on modern hardware. The renovation preserved algorithmic equivalence — verified by reproducing 1,800+ experiment runs with statistically matching results.

The broader project goal now goes beyond renovation: use the preserved snapshots, tests, and result artifacts to converge on one gold-standard code line that can reproduce the PhD results and absorb the historically reported domains/results under a single validated umbrella.

Two top-level status artifacts now help answer broader repo questions quickly:

• REPOSITORY-STATUS.md: repo-wide indexing/integration/testing/publication

status table

• REPOSITORY-STRUCTURE-REVIEW.md: filesystem clarity review and

classification guide

• docs/project-handbook.html: generated full readable handbook that pulls the

current core docs together into one indexed page

New material intake now has one dedicated landing zone:

• incoming/: single bucket for newly found relevant code, data,

publications, and experiment artifacts before review and promotion

Architecture

Four ASDF Systems

The project contains four independent ASDF systems that share the same architecture but represent different development stages:

:qcsp3 is the primary system and the leading integration target. The others are historical snapshots kept for comparison, provenance, and regression anchoring. All four load independently and cannot be loaded simultaneously (they define overlapping function names in separate packages).

Source File Roles

Each system has the same core files (loaded in this order via ASDF :serial t):

Key Entry Points

;; N-Queens (deterministic, good for testing)
(qcsp3:qc 4)          ; 4-Queens with AC-3 → :complete
(qcsp3:qc 8)          ; 8-Queens with AC-3 → :complete

;; ADT recognition (uses random seed for noise generation)
(qcsp3:adt :random-ident "unique")

;; MPR recognition
(qcsp3:mpr :random-ident "unique")

;; Two-phase memory-based search
(qcsp3:memory-search "quilici-t1-index" "quilici-t1"
  :sit-noise 0 :random-ident "unique")

Domain-Switching Load Calls

CRITICAL: The queens.lisp, adt-setup.lisp, and mpr-setup.lisp files contain runtime (load ...) calls that reload domain-specific function definitions when switching between queens/ADT/MPR domains. These are NOT dead code and MUST NOT be removed. They exist because the same function names (e.g., constraint checkers) are redefined per domain.

Cross-Package Symbol Comparison

All four systems use (string-equal random-ident "unique") instead of (eq random-ident 'unique) because 'unique resolves to different symbols in different packages. Any new cross-package symbol comparisons should use string-equal or compare via symbol-name.

Package Exports

All four packages export:

q qs qc cq cqs cqc queens adt mpr bm backtracking ac-3
set-globals show-solution show-options comment1 *unix*
*constraint-cks* *node-consistency-checks*
*backtrack-nodes-created* *nodes-visited*

qcsp3/may29/alex additionally export:

adt-gsat memory-search quilici-search

Build and Test Commands

# Load into REPL
sbcl --load "src/main.lisp"

# Run all FiveAM test suites (4 systems, 25 tests, ~90 assertions)
sbcl --non-interactive --load "tests/run.lisp"

# Run asserted AO coverage
sbcl --non-interactive --load "tests/ao-run.lisp"

# Run individual suites
sbcl --non-interactive --load "tests/csp-suite.lisp"
sbcl --non-interactive --load "tests/qcsp3-suite.lisp"
sbcl --non-interactive --load "tests/may29-suite.lisp"
sbcl --non-interactive --load "tests/alex-suite.lisp"

# Legacy/manual AO harnesses
sbcl --non-interactive --load "run-test4.lisp"
sbcl --non-interactive --load "run-test4-may29.lisp"
sbcl --non-interactive --load "run-test4-alex.lisp"

# Full supported validation spine
bash tests/validate-artifacts.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-ao.sh

# Run experiments (takes hours — generates 200 data points each)
bash Q-Batch-SBCL/ij2.sh
bash Q-Batch-SBCL/ij3.sh
bash Q-Batch-SBCL/ij4.sh
bash Q-Batch-SBCL/run-may29-all.sh
bash Q-Batch-SBCL/run-alex-all.sh

# Generate comparison plots (requires matplotlib)
python3 Q-Batch-SBCL/Graph/compare-all-overlay.py   # reads ACL baselines from data/acl-experiments/Graph

CI

GitHub Actions runs tests/run.lisp, the artifact validation smoke test (tests/validate-artifacts.sh), the preserved ff* provenance check (tests/validate-ff-provenance.sh), and the asserted AO regression validation (tests/validate-ao.sh, backed by tests/ao-run.lisp) on every push to main and on PRs. See .github/workflows/test.yml.

Test Architecture

Tests run in separate SBCL processes (one per suite) because the four systems cannot coexist in a single Lisp image. tests/run.lisp orchestrates this.

tests/ is the authoritative supported validation surface. The repo-root run-test4*.lisp scripts remain useful historical/manual harnesses, but CI and day-to-day confidence checks should flow through:

• tests/run.lisp
• tests/ao-run.lisp
• tests/validate-artifacts.sh
• tests/validate-ff-provenance.sh
• tests/validate-ao.sh
• tests/validate-thesis-comparison.py

Each suite:

1. Loads Quicklisp and FiveAM
2. Registers the project root with ASDF
3. Loads one ASDF system
4. Runs FiveAM tests with exact metric assertions
5. Exits with code 0 (pass) or 1 (fail)

What the Tests Assert

• Queens (deterministic): exact TCC, backtrack count, nodes visited
• ADT/MPR (random seed "unique"): exact NCC, TCC upper-bound ceiling
• Memory-search: exact NCC, TCC upper-bound ceiling
• Return values: :complete, consp (for memory-search results)

Project Layout

csp/                           Base CSP solver (14 source .lisp files)
  README.md                    Snapshot guide and file-role orientation
qcsp3/                         Extended solver (13 source files + extras/)
qcsp-may29-1996/               May 1996 snapshot (13 source + extras/ + batch data)
qcsp-alex-sep16-1997/          Sep 1997 snapshot (14 source + extras/ + testdata/)
data/                          Consolidated data directory (see data/README.md)
  sparc-archive/               Original SPARC archive listings (1993-1997)
  acl-experiments/             ACL-era ij2/ij3/ij4 experiment results
  csp-batch/                   Earliest batch experiments (T1-T6)
  csp-adt-batch/               ADT domain batch experiments
  csp-save-results/            DREV memorandum results (1993)
  csp-misc/                    C source, parsers, docs, utility scripts
  motors-releases/             MOTORS solver releases (.tar.Z, 1993)
  motors-backups/              MOTORS solver backups (.zoo, 1994)
  thesis/                      PhD thesis PDF
  lost-datasets.md             QCSP-nov96 terrain/TCSP recovery guide
Q-Batch-SBCL/                  SBCL experiment infrastructure
  README.md                    Experiment/workspace guide
  Graph/                       Analysis scripts and comparison plots
tests/                         FiveAM test suites
  README.md                    Validation entry points and coverage guide
  run.lisp                     Test orchestrator (runs all 4 suites)
  csp-suite.lisp               CSP tests (4 tests)
  qcsp3-suite.lisp             QCSP3 tests (8 tests)
  may29-suite.lisp             May29 tests (5 tests)
  alex-suite.lisp              Alex tests (5 tests)
  ao-run.lisp                  Asserted AO regression runner
  validate-artifacts.sh        Thesis artifact regeneration/validation
  validate-ff-provenance.sh    NewData4b/PrevResults integrity check
  validate-ao.sh               AO validation wrapper
  validate-thesis-comparison.py ACL-vs-SBCL thesis baseline check
src/main.lisp                  REPL entry point
*.asd                          ASDF system definitions (4 files)
run-test4*.lisp                Legacy/manual AO harnesses (3 files)

Known Pitfalls

These are hard-won lessons from the ACL-to-SBCL renovation. Any AI assistant working on this code should be aware of them.

1. defconstant with mutable values

SBCL enforces defconstant semantics strictly. If a constant is defined with a list value, reloading the file fails because the new list is not eql to the old one. Use defparameter instead for any non-numeric, non-character, non-symbol constant.

2. Domain-switching (load ...) calls

The (load ...) calls in queens.lisp, adt-setup.lisp, and mpr-setup.lisp are runtime domain switches, not build-time includes. They reload constraint definitions when switching problem domains. Do not remove them or convert them to ASDF dependencies.

3. domain-loaded gets overwritten

ASDF loads files in serial order. If queens.lisp sets *domain-loaded* to 'queens, then adt-simple.lisp (loaded later) overwrites it to 'adt. The runtime (load ...) calls reset it correctly when a domain is actually invoked.

4. set-globals argument counts differ

set-globals takes different numbers of parameters across systems:

• csp/qcsp3: 16 parameters
• may29: 18 parameters
• alex: 20 parameters

Callers in queens.lisp were fixed to pass the correct count with nil placeholders. If you modify set-globals, check all callers.

5. Cross-package symbol identity

(eq random-ident 'unique) fails across packages because 'unique is PHD-QCSP3::UNIQUE in one package but KEYWORD:UNIQUE or CL-USER::UNIQUE in the caller. Always use string-equal for cross-package comparisons.

6. SBCL --eval accepts only single expressions

sbcl --eval "(form1) (form2)" fails with "Multiple expressions in --eval option." Write a temporary .lisp file and use --load instead, or chain multiple --eval flags.

7. Generated data directories must exist before tests

The solver writes to ADT-Random/, ADT-Situation/, MPR-Random/, MPR-Situation/ relative to the working directory. On CI (clean checkout), these don't exist. Test suites use (ensure-directories-exist "DIR/dummy") to create them. If you add a new test that writes data, include this call.

8. Alex ADT is limited

Alex's adt-setup.lisp has *template-object-list* commented out — it loads template data from external files not included in the repository. Alex ADT tests must explicitly pass :situation-id "quilici-i1" :template-id "quilici-t1" to use the inline Quilici data. The alex ADT-Situation/ directory is permanently empty.

9. Return values differ between systems

csp and qcsp3 bt.lisp return :complete (keyword). The original may29 and alex bt.lisp returned 'complete (package-internal symbol). This was normalized to :complete during renovation, but tests use string= on symbol-name as an extra safety net.

10. Stale .fasl files

SBCL compiles .lisp to .fasl. If you modify a source file but a stale .fasl exists, SBCL may warn "object file is older than source." Delete *.fasl in the source directories. They're in .gitignore.

Current State (March 2026)

What's Complete

• ACL-to-SBCL migration: All 4 systems compile and run cleanly on SBCL
• Package isolation: Each system in its own package with proper exports
• ASDF build system: 4 .asd files replacing manual load chains
• FiveAM test suites: 25 tests with TCC/NCC regression assertions
• GitHub Actions CI: Automated testing on push/PR
• Experiment replication: ij2/ij3/ij4 across qcsp3, may29, and alex

with ACL-vs-SBCL comparison plots and automated thesis-trend validation

• Integration tests: Arc-oriented (AO) solver tests for qcsp3, may29, alex
• Data consolidation: All datasets cataloged in data/ with READMEs
• Warning cleanup: 0 WARNING conditions across all systems (only

intentional STYLE-WARNINGs from domain function redefinitions)

• Bug fixes: 8+ latent bugs found and fixed during renovation
• Documentation: README, RENOVATION.md, DEVELOPMENT.md, data/README.md

What's Open

• Issue #4: QCSP-nov96 terrain CSP code — 3 source files completely lost

from the working tree (terrain-setup.lisp, terrain-simple.lisp, closure.lisp). Recovery now has a concrete lead: a Lacie1 historical drive reportedly containing terrain data and the generator. See data/lost-datasets.md.

What Could Be Improved

See GitHub Issues for tracked items. Potential improvements:

1. Suppress remaining STYLE-WARNINGs — intentional domain-switching

redefinitions still emit ~20 STYLE-WARNINGs per system load. Could be muffled with sb-ext:muffle-conditions in the redefinition sites.

1. Add confused-queens metric assertions — cqc (confused N-Queens)

tests only assert :complete, not specific TCC/BT counts.

1. Extend thesis-results comparison further back — CI now checks the

supported ACL ij2/ij3/ij4 baselines against regenerated SBCL tables. A later improvement would tie the older data/sparc-archive/PrevResults/ff*.ci family to a documented modern mapping.

1. Code documentation — the core algorithms (backtracking, AC-3, memory-CSP)

have minimal inline comments. Adding docstrings to key functions would help future understanding.

1. Explore alex DFA features — alex has node-type-consis and

dfa-rearrangement parameters that default to nil. Enabling them in ij4 experiments might close the alex TCC divergence gap.

1. Recover QCSP-nov96 — sort the Lacie1 terrain/generator lead and any

late-1996 backup media so the terrain domain can move from blocked archive lore toward a real validation family.

File Modification Guidelines

• Do not modify core algorithm files (bm.lisp, bt.lisp, ct.lisp) unless

fixing a verified bug. The renovation deliberately preserved algorithmic behavior.

• Test after every change: sbcl --non-interactive --load "tests/run.lisp"
• Queens tests are deterministic — if queens metrics change, something

is wrong with the core search.

• ADT/MPR NCC is deterministic with random-ident "unique". TCC varies

due to random noise generation but should stay within the test ceilings.

• All test suites must pass before committing.

Dependencies

• SBCL (any recent version, 2.4+)
• Quicklisp (for FiveAM test framework only — no other external deps)
• Python 3 + matplotlib (optional, for generating comparison plots)
• Gnuplot (optional, for legacy plot scripts)

The solver itself has zero external dependencies beyond Common Lisp.

Primary integrated solver line and current operational center of the project. This directory backs the :qcsp3 ASDF system and is the leading candidate for the eventual gold-standard codebase.

Loaded via ASDF system :qcsp3 (defined in qcsp3.asd at the repository root).

Role

qcsp3/ is where the supported post-M1 solver story comes together:

• the executable PhD-result baseline,
• the main ADT and MPR entry points,
• the two-phase memory-based search,
• the preserved Quilici-style search implementation,
• and the shared AO support used by the supported test4 validation path.

If you are trying to understand the active integrated line rather than the historical comparison snapshots, start here.

Core ASDF Files

Main Public Entry Points

Recent 0.3.x work is also pushing more operator guidance into the code itself. In a REPL you can inspect the active docstrings directly:

(documentation 'qcsp3:backtracking 'function)
(documentation 'qcsp3:ac-3 'function)
(documentation 'qcsp3:memory-search 'function)
(documentation 'qcsp3:quilici-search 'function)

The most common interactive load path is still:

sbcl --load "src/main.lisp"

Directory Mix

This directory contains three kinds of material:

1. source files that define the supported qcsp3 solver line,
2. runtime-generated ADT/MPR working data, and
3. a small amount of preserved experiment/output material.

That means qcsp3/ is mostly code, but not code-only.

Subdirectories

Local guides now exist for the two mixed-use subareas that most often confuse readers:

• extras/README.md
• ADT-Batch/README.md

The active working-state data areas now also explain themselves locally:

• ADT-Random/README.md
• ADT-Situation/README.md
• MPR-Random/README.md
• MPR-Situation/README.md

AO Support In extras/

The extras/ directory is important, but it is not part of the ASDF system. It contains the arc-oriented support files used by:

• tests/ao-run.lisp
• run-test4.lisp
• run-test4-alex.lisp

Key files:

Supported Validation Relationship

qcsp3/ is covered by the main supported validation spine through:

• tests/run.lisp
• tests/validate-artifacts.sh
• tests/validate-ao.sh

In practice that means:

• queens, confused queens, ADT, MPR, and memory-search are regression-tested,
• the supported thesis ij2 / ij3 / ij4 story depends on this tree,
• and the bounded AO baseline now asserts qcsp3 cases 1-3 plus the wrapper

path under tests/ao-qcsp3-suite.lisp.

What Is Not In This Directory

• Canonical preserved thesis-era baselines live under data/, not here.
• The modern batch experiment orchestration lives under Q-Batch-SBCL/, not

here.

• Historical comparison snapshots live under csp/,

qcsp-may29-1996/, and qcsp-alex-sep16-1997/.

Practical Reading Order

If you are orienting quickly:

1. package.lisp
2. queens.lisp
3. adt-simple.lisp
4. mpr-simple.lisp
5. memory-csp.lisp
6. utility.lisp
7. extras/ only if you are working on AO / test4

Local guide to the base csp snapshot's direct-ADT random-seed workspace.

Role

csp/ADT-Random/ stores seed files used by the earliest tracked solver root for direct ADT generation and replay.

These are:

• base-snapshot working-state artifacts,
• useful for lineage and comparison,
• but not a canonical preserved results family.

Important Distinction

Unlike later snapshots, the tracked base csp/ tree does not also carry a full adjacent ADT-Situation/ workspace. That difference is meaningful: the earliest root preserves the seed side more clearly than the later regenerated situation side.

Relationship To Other Areas

• Later snapshots (qcsp-may29-1996/, qcsp-alex-sep16-1997/, qcsp3/)

carry fuller ADT working-state layouts.

• data/csp-adt-batch/ is the preserved canonical ADT batch archive.

Rule Of Thumb

If you need the earliest tracked ADT seed lineage, start here.

If you need preserved batch outputs, use data/.

Local guide to the base csp snapshot's MPR random-seed workspace.

Role

csp/MPR-Random/ stores seed files for generated MPR situations in the earliest tracked solver root.

These files are:

• working-state reproducibility inputs,
• useful for understanding the earliest MPR generation lineage,
• not a standalone preserved publication/result family.

Relationship To Other Areas

• csp/MPR-Situation/ contains the paired generated MPR situation files.
• Later snapshots preserve similar directories with expanded solver behavior.

Rule Of Thumb

If you need the base snapshot's MPR seed lineage, start here.

Local guide to the base csp snapshot's generated MPR situation workspace.

Role

csp/MPR-Situation/ contains generated MPR situation files for the earliest tracked solver root.

This is working-state input data, not a canonical preserved results archive.

Current Shape

Like later snapshots, this directory uses multi-part hidden situation files such as:

• .Sit-test-1-ddist-0007241891-0.g
• .Sit-test-1-ddist-0007241891-0.p
• .Sit-test-1-ddist-0007241891-0.r
• .Sit-test-1-ddist-0007241891-0.y

There is also a nested Keep/ area, which should be read as preserved local holdover material rather than the primary active workspace surface.

Relationship To Other Areas

• csp/MPR-Random/ provides the paired seed lineage.
• Later snapshots (qcsp-may29-1996/, qcsp-alex-sep16-1997/, qcsp3/)

carry parallel MPR working-state directories with more surrounding infrastructure.

Rule Of Thumb

If you need to inspect the earliest tracked MPR input state, use this directory.

If you need validated preserved results, use the archive/data guides instead.

Local guide to the non-ASDF AO support layer under the primary integrated solver tree.

Role

qcsp3/extras/ is the preserved AO / test4 support workspace used by the supported legacy AO validation path. It is important, but it is not part of the main :qcsp3 ASDF load.

Think of this directory as:

• required for the bounded supported AO baseline,
• historically tied to the test4 family,
• and separate from the core queens / ADT / MPR / memory-search line.

What Loads It

The main current entry points are:

• tests/ao-run.lisp
• run-test4.lisp
• run-test4-may29.lisp
• run-test4-alex.lisp

If you only load src/main.lisp or the :qcsp3 ASDF system, these files are not loaded automatically.

File Roles

Supported Status

This directory is inside the supported validation umbrella, but only through a bounded surface:

• tests/ao-qcsp3-suite.lisp
• tests/ao-may29-suite.lisp
• tests/ao-alex-suite.lisp
• bash tests/validate-ao.sh

That means the repo currently treats these files as:

• supported enough for the asserted AO baseline,
• historically valuable beyond that,
• but not part of the main integrated solver line in the same way as

qcsp3/queens.lisp, qcsp3/adt-simple.lisp, or qcsp3/memory-csp.lisp.

Practical Reading Order

If you need to understand or debug this layer, read in this order:

1. test4.lisp
2. example-extend.lisp
3. ac-graph.lisp
4. ao-ac3.lisp and ao-ac-new.lisp
5. ao-revise-step.lisp and ao-revise-aggressive.lisp
6. applyr.lisp
7. hierarchy.lisp

What This Directory Is Not

• It is not the canonical home of the main integrated solver APIs.
• It is not part of the thesis ij2 / ij3 / ij4 result pipeline.
• It is not a general-purpose utility library for the rest of the repo.

Rule Of Thumb

If the task is about AO or test4, come here.

If the task is about the integrated solver line, start one level up in qcsp3/.

Local guide to the direct-ADT batch-style workspace under the primary solver tree.

Role

qcsp3/ADT-Batch/ is a mixed preserved/generated workspace that captures direct ADT batch-style runs under the qcsp3 snapshot. It is not the canonical preserved ADT batch archive for the project.

Use this directory as:

• a snapshot-local output/workspace area,
• a clue to how qcsp3 direct ADT runs were staged,
• and a reference point when comparing the maintained line against preserved

batch-style families.

Canonical Versus Local

The project's canonical preserved ADT batch family lives in:

• data/csp-adt-batch/

That archive is integrity-checked by:

• bash tests/validate-adt-batch.sh

This qcsp3/ADT-Batch/ directory is different:

• it belongs to the qcsp3 snapshot tree,
• it is useful for provenance and comparison,
• but it is not the main source of truth for the preserved historical

ij1-ij4 ADT batch archive.

Current Shape

The workspace currently contains many single-run outputs with names like:

• Test-ij4-050.1
• Test-ij4-100.1
• Test-ij4-1000.99

That naming pattern indicates:

• direct ADT family ij4,
• a noise level in the middle field,
• and a per-run/random suffix in the final field.

These are useful as a snapshot-local run record, but they should not be treated as the authoritative batch archive without comparing them back to data/csp-adt-batch/.

Relationship To The Current Roadmap

The repo now treats the broader ADT batch family as:

• historically important,
• integrity-checkable,
• but snapshot-specific rather than a required reproduction target for the

integrated qcsp3 line.

That means this directory has go-forward value mainly for:

• provenance,
• bridge investigation,
• and snapshot comparison.

It is not part of the supported current validation spine.

If You Are Investigating ADT Batch Again

Start with:

1. ADT-BATCH-INTEGRATION.md
2. data/csp-adt-batch/README.md
3. tests/README.md

Then use this directory only to answer snapshot-specific questions about qcsp3 output shape or naming.

Rule Of Thumb

If you want the preserved historical ADT batch archive, go to data/.

If you want the qcsp3 snapshot's own batch-style output workspace, use this directory.

Local guide to the qcsp3 snapshot's direct-ADT random-seed workspace.

Role

qcsp3/ADT-Random/ holds the random-state files used to generate or replay direct ADT experiment situations under the maintained qcsp3 line.

These files are:

• snapshot-local working data,
• important for experiment reproducibility and bridge investigation,
• but not the canonical preserved publication-result archive.

Naming Pattern

Files are typically named like:

• Rnd0805098560
• Rnd0145944017

The numeric suffix is the seed identity carried through related situation and batch outputs.

Relationship To Other Areas

• qcsp3/ADT-Situation/ contains the generated ADT situations built from

these seeds.

• Q-Batch-SBCL/ is the supported modern experiment workspace that consumes

maintained solver behavior.

• data/csp-adt-batch/ is the preserved canonical ADT batch archive; this

directory is not a replacement for it.

Supported Status

This directory is part of the maintained solver workspace and has go-forward value, but it is not validated directly as a standalone artifact family in the main test spine.

Its main roles are:

• supporting regenerable solver state,
• carrying seed lineage for investigations,
• and helping explain why two runs with the same domain settings may diverge.

Rule Of Thumb

If you are tracing direct-ADT seed lineage inside qcsp3, start here.

If you are looking for preserved historical results, start in data/ instead.

Local guide to the generated direct-ADT situation workspace under qcsp3.

Role

qcsp3/ADT-Situation/ contains generated ADT situation files produced from the maintained qcsp3 source definitions and random seeds.

This is a working-state directory, not a canonical preserved-results archive.

Naming Pattern

Situation files commonly look like:

• Sit-quilici-i1-dist1-0805098560-50
• Sit-quilici-i1-dist1-0805098560-1000

The pattern usually carries:

• situation family / source label,
• distribution label,
• random seed identity,
• and the noise level suffix.

What These Files Mean

These are solver inputs or regenerated intermediate artifacts, not final publication-level results. They are useful when you need to inspect:

• how much noise was injected,
• whether two maintained solver lines are building comparable situations,
• or where a bridge/integration mismatch begins before search starts.

Relationship To Other Areas

• qcsp3/ADT-Random/ holds the seed files paired with this directory.
• tests/investigate-adt-batch-*.sh uses this kind of material when tracing

ADT bridge divergence.

• data/csp-adt-batch/ remains the preserved historical ADT batch archive.

Supported Status

These files have operational value for the maintained line, but the directory is not itself treated as a canonical validated archive surface.

Think of it as:

• regenerable working data,
• useful for debugging and reproduction analysis,
• but secondary to the preserved result families under data/.

Rule Of Thumb

If you want to inspect the generated ADT input state for qcsp3, come here.

If you want stable preserved batch results, use data/csp-adt-batch/.

Local guide to the qcsp3 snapshot's MPR random-seed workspace.

Role

qcsp3/MPR-Random/ stores seed files for generated MPR situations under the maintained qcsp3 line.

These are working-state artifacts used to regenerate comparable MPR situations or to trace seed lineage during investigations.

Naming Pattern

Files are typically named like:

• Rnd0080215333
• Rnd3253070110

The seed identity is usually mirrored into the related generated situation files under qcsp3/MPR-Situation/.

Relationship To Other Areas

• qcsp3/MPR-Situation/ contains the generated MPR situations paired with

these seeds.

• qcsp3/mpr-simple.lisp and qcsp3/mpr-setup.lisp define the maintained MPR

domain behavior that consumes or regenerates this state.

• Historical preserved MPR-related materials live elsewhere in the snapshot

trees and archives; this directory is the maintained-line working copy.

Supported Status

This directory is part of the active solver workspace, but it is not a first-class validated artifact family on its own.

Its value is mostly:

• operational reproducibility,
• seed-trace debugging,
• and explaining generated MPR input state.

Rule Of Thumb

If you need the maintained MPR seeds for qcsp3, use this directory.

If you need publication/result provenance, start with the preserved data and snapshot documentation first.

Local guide to the generated MPR situation workspace under qcsp3.

Role

qcsp3/MPR-Situation/ contains generated MPR situation files for the maintained solver line.

These files represent generated domain inputs or intermediate working state, not canonical final result summaries.

Current Shape

Many files are hidden dotfiles with extensions like:

• .Sit-test-1-ddist-0080215333-0.g
• .Sit-test-1-ddist-0080215333-0.p
• .Sit-test-1-ddist-0080215333-0.r
• .Sit-test-1-ddist-0080215333-0.y

That layout indicates a multi-file per-situation representation rather than a single flat artifact.

What These Files Are Good For

They are useful when you need to understand:

• the generated maintained-line MPR input state,
• whether a seed produced the expected family of situation files,
• or whether a mismatch begins before search/reporting rather than during the

solver itself.

Relationship To Other Areas

• qcsp3/MPR-Random/ carries the seed files paired with this directory.
• qcsp3/mpr-simple.lisp and qcsp3/mpr-setup.lisp are the main maintained

code entry points for this domain.

• This directory is a working-state area, not the canonical source of

preserved publication results.

Supported Status

This directory supports the maintained solver line, but it is not validated as an independent archive family by the main test spine.

Treat it as:

• regenerable workspace state,
• useful for debugging and domain inspection,
• secondary to preserved archival result families.

Rule Of Thumb

If you need to inspect generated MPR inputs inside the active qcsp3 line, come here.

If you are tracing publication/result provenance, use data/ and the historical snapshot docs first.

Local guide to the May 29, 1996 snapshot's AO / test4 support layer.

Role

qcsp-may29-1996/extras/ contains the non-ASDF AO support files used by the May29 snapshot. This is the May29 counterpart to qcsp3/extras/.

It matters because:

• the supported AO validation spine still exercises this snapshot,
• the files preserve the mid-lineage AO implementation state,
• and they help explain the historical relationship between May29 and the

later integrated qcsp3 AO surface.

What Loads It

The main current entry points are:

• tests/ao-run.lisp
• run-test4-may29.lisp

These files are not part of the :qcsp-may29-1996 ASDF system by default.

File Roles

Supported Status

This directory participates in the supported validation umbrella only through the bounded AO path:

• tests/ao-may29-suite.lisp
• bash tests/validate-ao.sh

That means it is:

• supported for the asserted legacy AO baseline,
• historically meaningful beyond that,
• but not part of the main May29 ASDF load used by the core solver suites.

Relationship To qcsp3/extras

This directory and qcsp3/extras/ are intentionally similar.

In practice:

• May29 preserves the earlier snapshot-local AO layer,
• qcsp3/extras/ is the later integrated line's AO counterpart,
• and the current supported AO baseline compares them through the shared

asserted harness.

What This Directory Is Not

• It is not the canonical home of the main May29 solver APIs.
• It is not part of the thesis ij2 / ij3 / ij4 artifact pipeline.
• It is not a general utility directory for the rest of the snapshot.

Rule Of Thumb

If the task is about May29 AO behavior or run-test4-may29.lisp, start here.

If the task is about the May29 snapshot's main solver line, start one level up in qcsp-may29-1996/.

Local guide to the May29 snapshot's direct-ADT random-seed workspace.

Role

qcsp-may29-1996/ADT-Random/ stores seed files used to generate or replay direct ADT situations inside the May 29, 1996 snapshot.

These files are:

• snapshot-local working data,
• useful for historical replay and comparison,
• but not the canonical preserved result archive for the project.

Relationship To Other Areas

• qcsp-may29-1996/ADT-Situation/ contains the paired generated situations.
• qcsp-may29-1996/ADT-SituationMar96/ preserves an older ADT situation layer

and should not be confused with the active May29 working directory.

• data/csp-adt-batch/ is the canonical preserved ADT batch archive.

Rule Of Thumb

If you need May29 seed lineage for ADT generation, start here.

If you need preserved historical batch results, use data/ first.

Local guide to the generated direct-ADT situation workspace under the May29 snapshot.

Role

qcsp-may29-1996/ADT-Situation/ contains generated ADT situations for the May29 solver line. These are working-state inputs or regenerated intermediates, not a canonical results archive.

Current Shape

Typical names look like:

• Sit-h-i2-dist1-0805098560-100
• Sit-h-i2-dist1-0805098560-2000

Those names usually encode:

• situation family,
• instance/distribution label,
• seed identity,
• and noise level.

Important Distinction

This directory is the active May29 working-state location.

The nearby ADT-SituationMar96/ directory is different: it preserves older March 1996 ADT situation material and should be treated as a preserved historical layer rather than the current May29 regeneration target.

Relationship To Other Areas

• qcsp-may29-1996/ADT-Random/ provides the seed files paired with this

directory.

• data/csp-adt-batch/ remains the canonical preserved ADT batch archive.
• qcsp-may29-1996/NewData4b-Batch/ and related batch trees preserve summary

outputs, not the same kind of input-state workspace found here.

Rule Of Thumb

If you want May29 generated ADT input state, use this directory.

If you want preserved archival outputs, start with data/ or the snapshot's batch/result trees.

Local guide to the older preserved March 1996 ADT situation layer.

Role

qcsp-may29-1996/ADT-SituationMar96/ is a preserved historical situation tree kept beside the active May29 ADT workspace for provenance.

This directory should be read as:

• older preserved material,
• useful for historical comparison,
• not the default regenerable May29 working-state directory.

Relationship To Nearby Directories

• qcsp-may29-1996/ADT-Situation/ is the active May29 generated situation

area.

• qcsp-may29-1996/ADT-Random/ holds the seed files used for May29-era

regeneration work.

Rule Of Thumb

If you are reading current May29 working state, use ADT-Situation/.

If you are tracing older preserved situation lineage, use this directory.

Local guide to the May29 snapshot's MPR random-seed workspace.

Role

qcsp-may29-1996/MPR-Random/ stores random-seed files used to generate or replay MPR situations in the May29 snapshot.

These are snapshot-local working artifacts, not a standalone preserved result family.

Relationship To Other Areas

• qcsp-may29-1996/MPR-Situation/ contains the paired generated MPR

situations.

• mpr-simple.lisp and mpr-setup.lisp define the code that uses or

regenerates this state.

Rule Of Thumb

If you need seed-level reproducibility for May29 MPR generation, start here.

Local guide to the generated MPR situation workspace under the May29 snapshot.

Role

qcsp-may29-1996/MPR-Situation/ contains generated MPR situation files for the May29 line.

Like the corresponding qcsp3 directory, this is working-state input material and not a canonical result archive.

Current Shape

Many files are hidden multi-part situation files such as:

• .Sit-test-1-ddist-0183914511-0.g
• .Sit-test-1-ddist-0183914511-0.p
• .Sit-test-1-ddist-0183914511-0.r
• .Sit-test-1-ddist-0183914511-0.y

That indicates a multi-file per-situation representation.

Relationship To Other Areas

• qcsp-may29-1996/MPR-Random/ provides the seed lineage.
• The main maintained result/provenance story for the project lives elsewhere;

this directory is snapshot-local generated state.

Rule Of Thumb

If you need May29 generated MPR inputs, come here.

If you need validated result families, use the preserved data/archive guides.

Local guide to the Alex snapshot's preserved batch orchestration tree.

Role

qcsp-alex-sep16-1997/MyBatch/ is a preserved Allegro-era batch runner workspace. It is not part of the supported modern validation spine, but it is valuable for provenance because it preserves how large experiment families were scripted under the Alex snapshot.

Use it as:

• a historical runner/orchestration archive,
• a clue to how thesis-era or near-thesis-era batch work was staged,
• and a reference when comparing the later maintained experiment workspace to

preserved historical tooling.

Current Shape

The tree has two main layers:

• batch-0.lisp through batch-23.lisp
• old-batch/ with older batch-exe-*, exp-*, and run-exp-* drivers

There are also a few shell/helper files such as:

• run-batch
• run-batch-yk
• one-more

This mix strongly suggests a preserved execution/control surface rather than a single coherent modern workflow.

Relationship To Other Areas

This directory is related to, but not the same as:

• Q-Batch-SBCL/ for the supported modern experiment workspace,
• historical finds/yj-sun/Csp/ for related recovered orchestration/provenance

material,

• qcsp-alex-sep16-1997/testdata/ for the preserved result/data side of the

Alex snapshot.

Supported Status

MyBatch/ is currently treated as:

• preserved historical tooling,
• useful for provenance and reconstruction,
• but not part of the supported current build or validation gate.

The repo does not currently claim that these batch drivers can be rerun cleanly on the maintained modern path.

What This Directory Is Good For

This tree is especially useful for:

• understanding how experiment families were chunked,
• identifying old experiment naming conventions,
• tracing possible generator/runner lineage for preserved result trees,
• and supporting archive interpretation work.

What This Directory Is Not

• It is not the canonical active experiment workspace.
• It is not the source of truth for supported current CI checks.
• It is not a maintained operator-facing workflow for day-to-day use.

Rule Of Thumb

If the task is about preserved Alex-era batch orchestration, use this directory.

If the task is about running supported experiments today, use Q-Batch-SBCL/ instead.

Local guide to the main preserved results tree under the Alex snapshot's testdata/.

Role

qcsp-alex-sep16-1997/testdata/Results/ is the broad preserved experiment results area for the Alex snapshot. It is historically important, but it is not part of the current supported validation spine.

Use it as:

• a preserved result-family archive,
• a provenance source for Alex-era experiments,
• and a reference when interpreting testdata/ as a whole.

Main Subfamilies

Rule Of Thumb

If you need the broad Alex preserved result families, start here.

If you need the supported modern experiment path, use Q-Batch-SBCL/ instead.

Local guide to the loop-analysis result subtree under the Alex snapshot's testdata/.

Role

qcsp-alex-sep16-1997/testdata/Results-Loop/ preserves a specialized loop-focused result family that sits beside the broader Results/ tree.

This is archive/provenance material, not a supported active validation surface.

Current Shape

The tree includes:

• loop-oriented preserved results,
• and a before-dec-30/ historical layer.

Relationship To Other Areas

• testdata/Results/ is the broader preserved Alex results tree.
• testdata/thesis-results/ is the publication-layout layer.
• Q-Batch-SBCL/ is the supported modern experiment workspace.

Rule Of Thumb

Use this directory when the question is specifically about preserved loop-analysis results, not when you want the main current experiment path.

Local guide to the Alex snapshot's direct-ADT random-seed workspace.

Role

qcsp-alex-sep16-1997/ADT-Random/ stores seed files for generated ADT situations under the Alex snapshot.

These files are useful for:

• reproducing snapshot-local generation,
• comparing seed lineage with May29 and qcsp3,
• and explaining drift in later bridge investigations.

They are not the canonical preserved result archive.

Relationship To Other Areas

• qcsp-alex-sep16-1997/ADT-Situation/ is the paired situation workspace.
• historical finds/yj-sun/Csp/ may carry related lineage, but this directory

is the tracked Alex snapshot copy.

Rule Of Thumb

If you need Alex seed lineage for ADT generation, start here.

Local guide to the Alex snapshot's direct-ADT situation workspace.

Role

qcsp-alex-sep16-1997/ADT-Situation/ is the tracked location for generated ADT situations under the Alex snapshot.

At the moment this directory is sparse compared with other snapshot workspaces, which is itself useful information: the tracked Alex tree preserves the generation surface, but not necessarily a large carried situation corpus.

Relationship To Other Areas

• qcsp-alex-sep16-1997/ADT-Random/ provides the paired seed files.
• testdata/ and MyBatch/ preserve more of the Alex result/orchestration

story than this directory does.

Rule Of Thumb

Treat this as a snapshot-local working-state location, not as a canonical historical results archive.

Local guide to the Alex snapshot's MPR random-seed workspace.

Role

qcsp-alex-sep16-1997/MPR-Random/ stores seed files used to generate or replay MPR situations in the Alex snapshot.

These are snapshot-local working-state artifacts with provenance value, not a standalone validated results family.

Relationship To Other Areas

• qcsp-alex-sep16-1997/MPR-Situation/ is the paired generated situation area.
• The Alex snapshot's published-result story is carried more directly in

testdata/ and related preserved experiment trees.

Rule Of Thumb

If you need Alex MPR seed lineage, start here.

Local guide to the Alex snapshot's generated MPR situation workspace.

Role

qcsp-alex-sep16-1997/MPR-Situation/ contains generated MPR situation files for the Alex solver snapshot.

This is a working-state input area, not the main preserved results/archive surface for the Alex tree.

Current Shape

Like the other solver snapshots, this directory uses multi-part hidden situation files such as:

• .Sit-test-1-ddist-0145944017-0.g
• .Sit-test-1-ddist-0145944017-0.p
• .Sit-test-1-ddist-0145944017-0.r
• .Sit-test-1-ddist-0145944017-0.y

Relationship To Other Areas

• qcsp-alex-sep16-1997/MPR-Random/ carries the paired seed lineage.
• qcsp-alex-sep16-1997/testdata/ is the more important preserved

publication/result-side area for this snapshot.

Rule Of Thumb

If you need Alex generated MPR input state, use this directory.

If you need preserved experimental outputs, start with testdata/.

This directory contains the modern interactive entry point for the renovated project.

Purpose

src/main.lisp is the supported "load the solver and start exploring" workflow.

Use it when you want:

• a REPL with the primary integrated solver line loaded,
• the working directory set up for ADT and MPR runs,
• and the common qcsp3: entry points ready to call interactively.

Supported Load Path

From the repository root:

sbcl --load "src/main.lisp"

That path:

1. registers the repo with ASDF,
2. loads :qcsp3,
3. points the default working directory at qcsp3/,
4. ensures the runtime ADT directories exist, and
5. leaves you at a REPL with the main interactive commands available.

What This Is Not

• It is not the full validation spine. For that, use tests/.
• It is not the batch experiment workspace. For that, use Q-Batch-SBCL/.
• It is not how the historical comparison snapshots are normally loaded for

regression coverage; those are exercised through the test suites.

Typical Next Commands

After loading:

• (qcsp3:qc 4) for 4-Queens
• (qcsp3:cqc 4) for confused queens
• (qcsp3:adt) for direct ADT matching
• (qcsp3:mpr) for MPR
• (qcsp3:memory-search) for the two-phase memory-based path

Using In-Code Docs

The 0.3.x docs lane is also pushing more guidance directly into the Lisp entry points. From the REPL you can inspect those docstrings with:

(documentation 'qcsp3:backtracking 'function)
(documentation 'qcsp3:ac-3 'function)
(documentation 'qcsp3:memory-search 'function)
(documentation 'qcsp3:quilici-search 'function)

This is the fastest way to see what an entry point expects without leaving the interactive session.

Relationship To The Repo

If qcsp3/ is the main solver line and tests/ is the validation gate, src/ is the simplest supported operator entry point.

This directory is the authoritative validation surface for the renovated project. If the question is "what proves the current baseline still works?", start here.

Main Entry Points

• run.lisp: orchestrates the Four FiveAM suites in separate SBCL processes.
• ao-run.lisp: asserted AO regression runner for the supported test4

baseline across qcsp3, may29, and alex, now covering qcsp3/may29 AO cases 1-3 plus the legacy wrappers and alex's revise baseline.

• validate-artifacts.sh: rebuilds SBCL graph artifacts, regenerates overlay

plots, and checks the current thesis-result pipeline.

• validate-dashboard.sh: regenerates the visual release dashboard and the

full readable handbook plus the public-facing PhD project page and this repo's public status manifest from their shared status/doc sources, and fails if the checked-in outputs are out of sync.

• validate-ff-provenance.sh: checks that the preserved NewData4b-Batch

ff* graph summaries match their PrevResults/ carry-forward copies and that the supporting raw/count lineage is present.

• validate-adt-batch.sh: checks that the preserved data/csp-adt-batch/

ij1-ij4 raw file grids and historically uneven CI summary tables still line up as expected.

• validate-csp-batch.sh: checks that the preserved data/csp-batch/ and

data/csp-save-results/ DREV-era T1-T6 archive still matches its historical summary layout and known row-count quirks.

• investigate-adt-batch-bridge.sh: runs the first narrow executable bridge

case for the preserved ADT batch ij2 family and reports whether the current csp:adt output matches or diverges from the preserved archive. It now defaults to the closer surviving qcsp3 Rnddefault bundle, and PHD_ADT_BRIDGE_RANDOM_SOURCE=... can override that seed source for comparison runs.

• investigate-adt-batch-random-lineage.sh: reruns that same ij2 bridge

case against the surviving Rnddefault bundles from may29, qcsp3, alex, and historical finds/yj-sun/Csp to test whether random-state lineage is driving the divergence.

• investigate-adt-batch-input-shape.sh: inspects the generated ij2

situation and domain shape before search starts so we can tell whether the bridge mismatch begins in preprocessing or only later in the search. Under the current qcsp3-seeded bridge, it shows that Dsize and NCC already diverge before backtracking starts.

• investigate-adt-batch-source-drift.sh / run-adt-batch-input-shape-generic.lisp:

compare that pre-search ij2 shape across maintained source/dist variants. The current result is that qcsp3/dist1 is materially closer to the preserved ij2-050.1 preprocessing metrics than csp/dist1.

• investigate-adt-batch-qcsp3-bridge.sh / run-adt-batch-bridge-qcsp3-ij2.lisp:

run the same narrow ij2 bridge through maintained qcsp3 using a legacy-compatible temporary workdir. The current result is still divergent, but materially closer to the preserved case than the maintained csp bridge on the tracked non-timing metrics.

• investigate-adt-batch-qcsp3-old-dist1-bridge.sh:

reruns that same narrow ij2 qcsp3 bridge through a temporary normalized copy of the carried old-dist1-pre-quilici distribution. The current result is that the preserved pre-Quilici label is runnable in isolation, but it lands farther from the preserved ij2-050.1 metrics than maintained qcsp3/dist1.

• investigate-adt-batch-structure-drift.sh:

compares the generated ij2 situation profile and node-consistent domain shape for maintained csp/dist1 versus maintained qcsp3/dist1. The current result is that qcsp3 builds a smaller noise layer with fewer begin/end statements, more check statements, and the largest domain squeeze on t2-c.

• investigate-adt-batch-generator-drift.sh:

compares the maintained csp and qcsp3 ADT source definitions directly. The current result is that csp/dist1 and qcsp3/dist1 are different noise distributions, and qcsp3 also changed generator behavior beyond the raw weights.

• validate-ao.sh: shell wrapper that runs ao-run.lisp.
• validate-thesis-comparison.py: checks that regenerated SBCL ij2 / ij3 /

ij4 CI tables preserve the supported ACL baseline story.

Suite Breakdown

• csp-suite.lisp: base solver regression metrics.
• qcsp3-suite.lisp: primary solver regression metrics.
• may29-suite.lisp: May 29 1996 snapshot regression metrics.
• alex-suite.lisp: Sep 16 1997 alex snapshot regression metrics.
• ao-qcsp3-suite.lisp, ao-may29-suite.lisp, ao-alex-suite.lisp:

deterministic AO assertions for the supported test4 path, including the bounded M1 AO surface.

Supported Validation Spine

Run these from the repository root:

sbcl --non-interactive --load "tests/run.lisp"
bash tests/validate-artifacts.sh
bash tests/validate-dashboard.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-adt-batch.sh
bash tests/validate-csp-batch.sh
bash tests/validate-ao.sh

This is the baseline CI path and the best local confidence check before or after code changes. Fresh March 21, 2026 validation runs of tests/run.lisp and tests/validate-ao.sh are currently clean for the supported path, so any new warning output in those flows should be treated as a potential regression signal.

investigate-adt-batch-bridge.sh is intentionally outside that supported gate for now. It is an executable research/integration probe, not yet a passing baseline check.

Legacy AO Harnesses

The repo-root scripts:

• run-test4.lisp
• run-test4-may29.lisp
• run-test4-alex.lisp

are still useful as historical/manual harnesses, but tests/ao-run.lisp is the asserted path that CI treats as supported coverage.

This directory is the modern SBCL experiment workspace for thesis-result replication.

What Lives Here

• bootstrap*.lisp, gen-seeds*.lisp, generate-*.lisp: experiment setup and

script generation helpers.

• ij2*.lisp, ij3*.lisp, ij4*.lisp: generated per-noise experiment drivers.
• ij2.sh, ij3.sh, ij4.sh, run-may29-all.sh, run-alex-all.sh: runner

scripts for the supported experiment families.

• Graph/: data extraction, comparison plotting, and tracked overlay outputs.

See Graph/README.md for the local plotting/data-flow guide.

Result Layout

This directory mixes tracked experiment infrastructure with runtime-generated outputs:

• Tracked: runner scripts, bootstrap/generator Lisp files, Graph/*.py,

Graph/*.gp, and the checked-in comparison overlay PNGs.

• Generated at runtime: run directories such as ij2/, ij3/, ij4/,

may29-ij2/, may29-ij3/, may29-ij4/, alex-ij2/, alex-ij3/, alex-ij4/, plus console *.out files and extracted graph tables/PDFs.

If this directory looks busy, that is normal: it is both the experiment control surface and the scratch space for regenerated outputs.

Supported Workflow

Run experiments from the repository root:

bash Q-Batch-SBCL/ij2.sh
bash Q-Batch-SBCL/ij3.sh
bash Q-Batch-SBCL/ij4.sh
bash Q-Batch-SBCL/run-may29-all.sh
bash Q-Batch-SBCL/run-alex-all.sh

Regenerate comparison artifacts:

bash tests/validate-artifacts.sh

That validation path compares regenerated SBCL CI tables against the preserved ACL baseline under data/acl-experiments/Graph/.

Operator Split

Use this directory in two ways:

1. as the main experiment runner surface through the ij*.sh and

run-*-all.sh scripts,

1. as the parent workspace for the plotting/comparison layer under Graph/.

If the question is about rerunning experiment families, start here.

If the question is about extracted tables, overlay PNGs, or comparison PDFs, drop into Graph/README.md.

This directory is the thesis-result comparison and plotting surface for the modern SBCL experiment workspace.

Use it when the question is:

• where do the extracted CI tables come from,
• which files are generated versus tracked,
• and which scripts rebuild the plotted comparison story.

What Lives Here

Tracked plotting/control files

• extract-data.py
• compare-plots.py
• compare-ij2-overlay.py
• compare-all-overlay.py
• the *.gp gnuplot helpers

These are maintained operator/build files.

Generated comparison tables

Examples:

• ij2-ci.dat
• ij3-ci.dat
• ij4-ci.dat
• ij2-ci-time.dat
• ij3-other-ci.dat
• ij*-raw.dat

These are regenerated from the checked-in SBCL experiment outputs by tests/validate-artifacts.sh.

Generated visual outputs

Examples:

• compare-ij2-overlay.png
• compare-ij3-overlay.png
• compare-ij4-overlay.png
• compare-all-overlay.png
• compare-*.pdf

The overlay PNGs are tracked because they are part of the published/readable artifact surface for the repo. The PDF outputs are generated comparison artifacts.

Main Inputs

This directory combines:

1. regenerated SBCL summary tables from the local Q-Batch-SBCL/ runs,
2. preserved ACL baseline tables from data/acl-experiments/Graph/,
3. comparison plotting scripts that overlay qcsp3, may29, alex, and ACL views.

Supported Operator Flow

If you want the supported rebuild path, run:

bash tests/validate-artifacts.sh

That path:

1. extracts fresh SBCL CI tables,
2. regenerates the tracked overlay PNGs,
3. rebuilds the comparison PDFs,
4. and runs the thesis-comparison check that protects the published trend story.

Direct Script Use

Use the Python scripts directly only when you want a narrower/manual refresh:

python3 Q-Batch-SBCL/Graph/compare-plots.py
python3 Q-Batch-SBCL/Graph/compare-ij2-overlay.py
python3 Q-Batch-SBCL/Graph/compare-all-overlay.py

Use the gnuplot helpers when you specifically want the older plot path rather than the supported validation wrapper.

Rule Of Thumb

If the task is confidence in the thesis-result story, use tests/validate-artifacts.sh.

If the task is manual plot iteration or debugging one comparison layer, work directly in this directory.

Master index for all datasets in the PhD renovation project. This directory consolidates standalone data archives; snapshot-embedded and runtime-generated data remain in place and are cataloged here.

Consolidated Datasets

See also: lost-datasets.md for the Nov 1996 snapshot (terrain CSP data, never recovered).

Local guides worth using in place:

• acl-experiments/README.md explains the canonical ACL baseline used by the

supported thesis-validation path.

• sparc-archive/README.md explains the older SPARC-era preserved result

families and archive indexes.

• thesis/README.md explains how the thesis PDF relates to the active

validation story.

---

Snapshot-Embedded Data (left in place)

These datasets are embedded within historical code snapshots and are left in place to preserve snapshot integrity. Each is documented with a README.

qcsp-may29-1996/ (2,550+ data files)

qcsp-alex-sep16-1997/ (564 data files)

---

Active Experiment Infrastructure

Q-Batch-SBCL/ (not moved -- uses relative paths)

Modern SBCL experiment framework. Shell scripts and Lisp loaders reference relative paths to the 4 ASDF systems. See also Q-Batch-SBCL/README.md for the code/test/results layout inside that workspace.

Tracked files: bootstrap\.lisp, gen-seeds\.lisp, generate-experiments.lisp, ij\.lisp (45 experiment scripts), \.sh (6 runner scripts), diagnose-ij4.sh, Graph/\.py (4 Python scripts), Graph/\.gp (5 Gnuplot scripts), Graph/\*.png (4 comparison overlay plots).

Gitignored/runtime-generated:

• Result directories: ij2/, ij3/, ij4/, alex-ij2/, alex-ij3/, alex-ij4/,

may29-ij2/, may29-ij3/, may29-ij4/ (200 files each when populated)

• Console output: \*.out
• Extracted data: Graph/\.dat, \.all, \.p1, \.pdf

To regenerate experiments: bash Q-Batch-SBCL/ij2.sh (also ij3.sh, ij4.sh, run-may29-all.sh, run-alex-all.sh).

To regenerate the supported thesis-comparison artifacts: bash tests/validate-artifacts.sh.

---

Runtime-Generated Data (gitignored)

These directories are created by the solver at runtime. They are gitignored and regenerated on demand.

File formats:

• Rnd* files: Serialized Lisp random-state objects (~14 KB each, text)
• Sit-* files: Serialized Lisp situation structures (750 B - 800 KB, text)
• Naming: Sit-{domain}-{template}-{distribution}-{seed}-{noise}

Note: alex ADT-Situation/ is permanently empty because *template-object-list* is commented out in alex adt-setup.lisp (template data loads from external files not included in the repository).

---

Compressed/Binary Files

---

Missing/Lost Datasets

See lost-datasets.md for a full inventory of the November 1996 snapshot, which contained unique terrain CSP code and data that was never recovered from the original SPARC archive.

Key losses:

• terrain-setup.lisp, terrain-simple.lisp, closure.lisp -- terrain CSP source
• TCSP-Situation/, TCSP-Random/ -- terrain CSP data files
• Entire Nov 1996 snapshot source code

This directory is the single intake bucket for newly found material that may be relevant to the project:

• source trees
• datasets
• experiment outputs
• publications
• notes
• recovered archives

Think of this as the shell-friendly implementation of:

new relevant information to integrate

Purpose

Use incoming/ first whenever new material arrives and its final home is not yet settled.

Do not drop new finds directly into:

• qcsp3/
• csp/
• qcsp-may29-1996/
• qcsp-alex-sep16-1997/
• data/
• historical finds/

until that material has been reviewed.

Intake Workflow

1. Add the new material under any convenient subdirectory name.

If you already know the likely date/source, a dated name is helpful, for example:

• incoming/2026-03-21-lacie1/
• incoming/2026-04-02-sparc-cdrom/
• incoming/2026-04-10-paper-scan/

If not, a rough dump name is fine:

• incoming/lacie-drive-dump/
• incoming/old-sparc-stuff/
• incoming/misc-papers/

1. Add a short note describing:

• where it came from,
• what it appears to contain,
• and whether it looks like code, data, publication, or mixed material.

1. During review, normalize the folder label if the contents reveal a better

date/source naming scheme than the original dump name.

1. Update incoming/INDEX.md with one row for the new intake.
2. Review the intake before promoting anything out of incoming/.
3. After review, move or classify it into one of these destinations:

• data/ for canonical preserved datasets/publications
• historical finds/ for archive/recovery material
• a solver snapshot tree if it clearly belongs there
• DUPLICATES-REVIEW.md if it is a reviewed duplicate/redundant copy

Review Outcomes

Every reviewed intake should end in one of these states:

• promoted: moved into the main repo structure
• historical: retained under historical finds/
• duplicate: documented as redundant/canonical elsewhere
• reference-only: preserved, but not integrated
• pending: still under review

Promotion Destinations

The usual destinations mean:

Relation To The Rest Of The Repo

incoming/ is the only place where "unreviewed but relevant" material should accumulate.

That keeps three other zones clearer:

1. data/ means preserved/canonical results or publications,
2. historical finds/ means reviewed archive/recovery material,
3. the solver trees mean code or snapshot-local artifacts that already have a

justified home.

Rule Of Thumb

If the right home or the right date label is not obvious yet, it belongs in incoming/ first.

This directory is a staging area for newly recovered historical material that appears related to the PhD renovation project, but is not yet part of the validated thesis-result baseline.

New finds should land in incoming/ first. Move material into historical finds/ only after review shows that it belongs here as archive/recovery material rather than as canonical data, supported code, or a reviewed duplicate.

Treat everything here as archive intake first, source-of-truth second. Nothing in this directory should be assumed to define supported behavior until it has been cataloged, compared against the tracked snapshots, and either promoted into a documented recovery path or left as reference-only context.

Current Intake

yj-sun/

Most likely the highest-value recovery lead in this intake.

• Csp/ looks like a direct relative of the current Lisp solver lineage. It

contains many familiar files (adt-simple.lisp, mpr-setup.lisp, memory-csp.lisp, general-exp.lisp, test4.lisp, template.txt, testdata/Results/, MyBatch/, etc.) plus older variants and backups that are not all present in the modernized repo.

• Gen++/ appears to be the C/C++ analyzer generator toolchain used to produce

component/control representations for the plan-recognition experiments. It includes documentation, example queries, rule-checker code, and a mylisp/ area that may explain part of the historical input pipeline.

Working assumption: yj-sun/Csp is a recovery candidate for Phase 5 archive work, while yj-sun/Gen++ is an upstream toolchain archive that may help us understand how historical .component / .control inputs were produced.

See also: yj-sun/Csp/README.md for the first comparison pass against the tracked solver snapshots.

Unravel/

This looks like an external NIST release of the Unravel slicing tool, including source archives and two technical reports (NIST-IR-5691 volumes 1 and 2).

Working assumption: this is important context for neighboring program-analysis work, but it should remain reference-only unless we find direct evidence that it formed part of the thesis validation pipeline for this repo.

Local guide:

• Unravel/README.md

Refine/

This currently contains a small set of .pob artifacts under Progs/, with mostly empty companion directories.

Working assumption: these are likely historical tool outputs or snapshots worth preserving, but they are not yet understood well enough to integrate further.

Local guide:

• Refine/README.md

SurgA-Info and Unravel-changes/

These are small but useful provenance clues:

• SurgA-Info links SurgeonsA, tkXsurgeon, and unravel
• Unravel-changes/SteveLog contains notes about parser output, variable type

extensions, and dataflow representation needs

These notes may help connect Gen++, Unravel, and the Lisp experiments into one broader historical workflow.

Local guide:

• Unravel-changes/README.md

Handling Rules

1. Do not mix files from this directory into the validated baseline casually.
2. Preserve original filenames, directory layout, and timestamps where

possible.

1. Prefer cataloging and diffing text sources before touching binaries,

executables, or generated outputs.

1. When promoting anything out of this directory, document why it matters to

thesis-result validation or to archive recovery.

What This Directory Is Not

This directory is not:

• the main solver line,
• the canonical preserved baseline data area,
• or a dumping ground for unreviewed finds.

New material should enter through incoming/ first. Material only belongs here after review has established that it is best treated as archive/recovery or reference context.

Typical Outcomes After Review

Material reviewed here usually ends in one of these states:

Suggested Recovery Order

1. Compare yj-sun/Csp against the tracked solver snapshots to identify unique

source variants, missing helpers, and older experiment drivers.

1. Keep separating result families cleanly: yj-sun/Csp/testdata/Results/

explains part of PrevResults/, while the ff1 / ff2 / ff3 family now appears to belong to the qcsp-era NewData4b-Batch lineage rather than the older MyBatch lane.

1. Catalog yj-sun/Gen++ as an upstream toolchain archive and identify the

minimum subset needed to explain .component / .control generation.

1. Leave Unravel/, Refine/, and the note files as reference/context until a

direct dependency on thesis validation is established.

Rule Of Thumb

If the material helps explain how the historical project was assembled, but not what the current supported baseline should execute, this is probably the right place for it.

Local guide to the historical finds/Refine/ archive subtree.

Role

This directory appears to preserve auxiliary program/refinement material rather than a runnable mainline solver component.

The current tracked contents are:

• Progs/ with .pob program/object artifacts,
• Reports/,
• Tmp/.

Current Read

The strongest current interpretation is:

• useful archive/context material,
• possibly tied to refinement or slicing workflows around the same era as

other recovered tooling,

• but not part of the supported solver baseline or current validation spine.

Rule Of Thumb

Treat this directory as archive/context material unless a later provenance pass proves a tighter operational connection.

Local guide to the recovered Unravel subtree.

Role

This directory preserves an external program-slicing/tooling distribution, including:

• NIST documentation volumes,
• an upstream README,
• and a large unravel_r2.2+/ source/tool tree.

It is not part of the supported Lisp solver baseline.

Current Read

Unravel/ is best read as:

• a preserved external-tool dependency or context layer,
• important for historical interpretation,
• but not a maintained or integrated build target in this repo.

Rule Of Thumb

Use this directory for provenance and external-tool context, not for current repo workflows.

Local guide to the historical finds/Unravel-changes/ notes subtree.

Role

This directory is primarily a note/log layer rather than a codebase.

The key tracked item is:

• SteveLog

Current Read

These notes appear to capture observations about parser output, type handling, or related toolchain behavior around the Unravel/Gen++ side of the research environment.

That makes this directory:

• historically useful,
• potentially important for provenance interpretation,
• but not part of the supported integrated solver path.

Rule Of Thumb

Read this directory as explanatory notes that may connect recovered external tools to the Lisp-side experiments.

This directory is the canonical preserved ACL/SPARC-era baseline for the supported thesis-result validation path.

It contains the historical ij2 / ij3 / ij4 experiment families used as the reference side of the repo's modern ACL-vs-SBCL comparison checks.

Why This Directory Matters

If the question is "what published result story does the repo actively protect?", this directory is part of the answer.

The supported validation path:

1. regenerates SBCL ij2 / ij3 / ij4 summaries in Q-Batch-SBCL/Graph/,
2. compares them against the preserved ACL baseline here,
3. and checks that the thesis-era trend story is still preserved.

That means this directory is not just archival context. It is one of the main live reference baselines used by tests/validate-artifacts.sh and tests/validate-thesis-comparison.py.

Experiment Series

Three preserved experiment series compare CSP search strategies for program understanding:

Each series tests 20 noise levels (50-1000 in steps of 50) with 10 random seeds per level, for 200 attempted data points per series.

Structure

acl-experiments/
├── ij2/            raw ACL result files
├── ij3/            raw ACL result files
├── ij4/            raw ACL result files
├── Graph/          preserved graph data, gnuplot scripts, PostScript plots
├── ij*.lisp        ACL-era experiment definition scripts
├── ij*.out         console output logs
└── ij*.sh          ACL-era shell runner scripts

Canonical vs Preserved Duplicate

This is the canonical active copy of the ACL baseline.

qcsp-may29-1996/Q-Batch/ is a reviewed duplicate retained only for snapshot integrity. The supported modern validation path should read from data/acl-experiments/, not from the embedded May29 duplicate.

Result File Shape

Each raw result file (for example ij2/ij2-250.3) is a whitespace-separated single-line summary. Important fields include:

• Size: noise level
• Dsize: average domain size
• NCC: node consistency checks
• TCC: total constraint checks
• BT/V: backtracks / nodes visited

The raw ACL files are historical artifacts; the supported modern comparison path does not require every raw file to be perfect or complete. It uses the preserved graph summaries and shared noise-level overlap to validate the thesis story responsibly.

Graph Layer

Graph/ contains the preserved ACL analysis layer:

• ij*-ci.dat: confidence interval tables
• ij*-raw.*: older aggregated raw summaries
• *.gp: gnuplot scripts
• *.ps: PostScript output
• Makefile, Bad/, Heuristic-Errs/, Util/: historical support material

This preserved graph layer is the ACL side of the modern comparison against Q-Batch-SBCL/Graph/.

Relationship To The Modern SBCL Workspace

The modern experiment workspace lives in Q-Batch-SBCL/.

The normal supported flow is:

bash tests/validate-artifacts.sh

That path:

1. extracts fresh SBCL ij2 / ij3 / ij4 summaries,
2. rebuilds the overlay plots,
3. compares those summaries to this ACL baseline,
4. and checks that the published efficiency ordering and trend shape still hold.

The repo validates historical trend preservation, not point-for-point numerical identity across platforms.

Rule Of Thumb

If you are working on the active thesis-result validation story, this directory is a primary reference input.

If you are studying ACL-era runner mechanics, it is also a preserved source tree, but not the place from which the modern repo executes experiments.

This directory holds the thesis document that the repo is trying to make continuously checkable.

Canonical Source File

• Woods PHD CS-96-33 A Method of Program Understanding using Constraint Satisfaction.pdf

Generated Public Copies

The docs/status build exports stable public-facing copies from the canonical PDF:

• docs/phd-renovation-thesis.pdf
• docs/phd-renovation-thesis.ps

The PDF copy is a direct synchronized mirror of the canonical source file. The PostScript copy is generated from that same canonical PDF during the regular docs/status build so the project home page can link both formats from one stable place.

Why This Matters

The thesis is not just background reading in this project. It is the main publication target behind the supported validation story.

The repo's primary goal is to keep the solver, preserved baselines, and reproduction harnesses aligned tightly enough that the thesis-result story remains explainable from a fresh checkout.

What The Thesis Covers

At a high level, the thesis:

• presents program understanding as a constraint-satisfaction problem,
• uses ADT recognition as the central application domain,
• introduces the memory-CSP two-phase search methodology,
• and compares it against direct CSP matching and related search variants

under increasing noise.

Practical Repo Relationship

These repo areas are the closest operational companions to the thesis:

Rule Of Thumb

If you want the publication narrative, start with the thesis PDF.

If you want the supported executable approximation of that narrative, start with data/acl-experiments/, Q-Batch-SBCL/, and tests/validate-artifacts.sh.

This file is the short map of the repo's main operator-facing workflows.

Use it when the question is not "what does this directory contain?" but "what do I run for the task in front of me?"

Supported Primary Workflows

1. Interactive Solver Use

Use this when you want a REPL with the primary integrated solver line loaded.

sbcl --load "src/main.lisp"

Best for:

• trying qcsp3: entry points by hand,
• exploring queens, ADT, MPR, or memory search interactively,
• quick operator checks that do not need the full regression spine.

Main guide: src/README.md

2. Full Validation Spine

Use this when you want the supported confidence check for the repo.

sbcl --non-interactive --load "tests/run.lisp"
bash tests/validate-artifacts.sh
bash tests/validate-dashboard.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-adt-batch.sh
bash tests/validate-csp-batch.sh
bash tests/validate-ao.sh

Best for:

• pre-merge confidence,
• post-change regression checks,
• confirming the supported thesis-validation baseline and status outputs.

Main guide: tests/README.md

3. Thesis Experiment Replication

Use this when you want to regenerate the supported SBCL experiment families.

bash Q-Batch-SBCL/ij2.sh
bash Q-Batch-SBCL/ij3.sh
bash Q-Batch-SBCL/ij4.sh
bash Q-Batch-SBCL/run-may29-all.sh
bash Q-Batch-SBCL/run-alex-all.sh

Best for:

• regenerating the modern experiment workspace,
• comparing qcsp3, may29, alex, and preserved ACL baselines,
• rebuilding the plotted thesis-result story.

Main guide: Q-Batch-SBCL/README.md Plot/data-flow guide: Q-Batch-SBCL/Graph/README.md

4. Status, Dashboard, Handbook, And Public Page Sync

Use this when plan/status wording changes.

python3 tools/generate-release-dashboard.py
bash tests/validate-dashboard.sh

Best for:

• keeping the release dashboard, full handbook, public project page, and

status manifest in sync,

• validating that generated docs/status outputs match the structured source

data and tracked markdown sources.

Main sources:

• docs/release-dashboard-data.json
• tools/generate-release-dashboard.py
• docs/README.md
• tools/README.md

5. Release Hardening

Use this when preparing a 1.0.0 release candidate.

python3 tools/generate-release-dashboard.py
sbcl --non-interactive --load "tests/run.lisp"
bash tests/validate-artifacts.sh
bash tests/validate-ff-provenance.sh
bash tests/validate-adt-batch.sh
bash tests/validate-csp-batch.sh
bash tests/validate-ao.sh
bash tests/validate-dashboard.sh

Best for:

• final release-candidate confidence,
• making sure the public/status outputs are current,
• checking the exact release gate in RELEASE-1.0-CHECKLIST.md.

Main guides:

• RELEASE-1.0-CHECKLIST.md
• RENOVATION.md

6. New Material Intake

Use this when new code, data, papers, or experiment artifacts arrive.

1. Drop the material under incoming/ using any convenient dump name.
2. Review it.
3. Normalize the intake folder label if the contents reveal a better date/source.
4. Update incoming/INDEX.md.
5. Promote it into data/, historical finds/, a snapshot tree, or

DUPLICATES-REVIEW.md.

Main guides:

• incoming/README.md
• incoming/INDEX.md

Secondary / Manual Workflows

These are still useful, but they are not the main supported operator path.

Manual AO Harnesses

sbcl --non-interactive --load "run-test4.lisp"
sbcl --non-interactive --load "run-test4-may29.lisp"
sbcl --non-interactive --load "run-test4-alex.lisp"

Use these for:

• historical/manual AO checking,
• understanding the legacy test4 loaders,
• comparing the manual harnesses to the asserted AO runner.

Supported AO confidence still comes from tests/ao-run.lisp.

Legacy Loader / Renovation Helpers

• run-csp-tests.lisp
• renovate.lisp

These remain part of the repo's historical/operator context, but they are not the primary supported flow for current work.

Rule Of Thumb

If the task is about confidence, use tests/.

If the task is about interactive solver use, use src/main.lisp.

If the task is about the thesis-result experiment story, use Q-Batch-SBCL/.

If the task is about new finds, use incoming/ first.

This directory contains generated project-status and handbook outputs plus the structured source data that drives them.

Use this guide when you want to answer:

• which files here are authoritative inputs,
• which ones are generated outputs,
• and which ones are mirrored to the public Pages repo.

Authoritative Source

release-dashboard-data.json is the main structured status source for the generated project views.

It carries the current build line, focus, roadmap timeline, handbook refresh policy, and the short public-facing status story used across the generated outputs.

If the roadmap meaningfully moves, the current blocker changes, the harness materially changes, or the release focus shifts, update this file and then regenerate the outputs.

Generated Repo Outputs

These files are generated from the structured status source and markdown docs:

Do not hand-edit the generated HTML or JSON here unless you are debugging the generator itself. The normal path is to update the markdown or release-dashboard-data.json, then regenerate.

Public Sync Role

The repo build produces the PhD-owned public assets that are later copied into the public Pages repo:

• phd-renovation.html
• phd-renovation-handbook.html
• phd-renovation-dashboard.html
• phd-renovation-thesis.pdf
• phd-renovation-thesis.ps
• data/projects/phd-renovation.json

The shared public index.html is no longer owned directly by this repo. Instead, this repo exports its project status through public-status-phd-renovation.json in the interface format.

Normal Regeneration Flow

python3 tools/generate-release-dashboard.py
bash tests/validate-dashboard.sh

That regeneration step updates the dashboard, handbook, public page source, public handbook source, status manifest, and the stable thesis PDF/PS copies together.

Rule Of Thumb

If the question is "what is the current official project status view?", start here.

If the question is "how are these generated?", see tools/README.md.

This directory contains the repo's maintained documentation/status generators.

Use this guide when you want to know which script owns the dashboard, handbook, public page, or status manifest.

Primary Scripts

generate-release-dashboard.py

This is the top-level status/doc generation entry point.

It regenerates the project-facing outputs that need to stay synchronized:

• docs/release-dashboard.html
• docs/public-phd-renovation.html
• docs/public-status-phd-renovation.json
• docs/project-handbook.html
• docs/public-phd-renovation-handbook.html
• docs/phd-renovation-thesis.pdf
• docs/phd-renovation-thesis.ps

Run this after any meaningful roadmap, blocker, harness, or release-focus change.

generate_project_handbook.py

This builds the long-form handbook from the repo's source markdown documents.

Normally you do not need to call it directly, because generate-release-dashboard.py already includes it as part of the regular docs/status build.

Use it directly only when debugging handbook generation in isolation.

Source Ownership

The generators draw from:

• docs/release-dashboard-data.json for structured roadmap/status data
• the tracked markdown documents listed in generate_project_handbook.py

If a new guide should appear in the handbook, add it to the handbook source list in generate_project_handbook.py.

Validation Pair

The supported validation check for these scripts is:

python3 tools/generate-release-dashboard.py
bash tests/validate-dashboard.sh

If validation fails after a source change, the generated files in docs/ are out of date or inconsistent with the expected public/status outputs and exported thesis assets.

Rule Of Thumb

Update source docs and status data first.

Then regenerate through generate-release-dashboard.py.

Then validate with tests/validate-dashboard.sh.

This file explains the repo-root helper scripts that are still useful but are not the primary supported workflow.

Use this when you are looking at the top-level .lisp files and want to know which ones are historical/manual helpers versus which ones define the mainline operator path.

Supported Mainline Alternatives

If your goal is one of these tasks, prefer the supported mainline entry points:

Root Helper Scripts

run-test4.lisp

Manual qcsp3 AO loader and runner for the legacy test4 harness.

Use it when:

• you want to see the historical manual AO flow,
• you want the printed manual harness output,
• or you are comparing the manual path against the asserted AO baseline.

Preferred supported counterpart:

• tests/ao-run.lisp
• tests/validate-ao.sh

run-test4-may29.lisp

Manual AO harness for the qcsp-may29-1996 snapshot.

Use it for manual/historical comparison work, not as the main confidence gate.

run-test4-alex.lisp

Manual AO harness for the alex snapshot.

This one is especially historical in flavor because alex reuses AO support from qcsp3/extras/ rather than carrying a self-contained AO tree of its own.

run-csp-tests.lisp

Manual loader that runs a small base-snapshot smoke pass in csp/.

Useful for:

• quick manual comparison against the older base snapshot,
• historical orientation,
• checking the older loader style.

Preferred supported counterpart:

• tests/run.lisp

renovate.lisp

Minimal bootstrap loader for :phd-research.

Useful for:

• historical renovation/bootstrap context,
• loading the earliest maintained solver line directly.

Preferred interactive counterpart:

• src/main.lisp

Rule Of Thumb

These root helpers are worth keeping because they preserve historical usage and manual comparison paths.

They are not the repo's primary operator surface.

If you are choosing where to start today:

1. use src/main.lisp for interactive work,
2. use tests/ for confidence,
3. use Q-Batch-SBCL/ for experiments,
4. use the root helpers only when you specifically want the historical/manual

path.

This file records the investigation state for the preserved ADT batch family.

Current project decision:

treat the preserved ADT batch ij1-ij4 family as a snapshot-specific, integrity-checkable historical family rather than a required reproduction target for the integrated qcsp3 line.

It remains historically important, and the repo keeps the bridge probes because they explain the divergence. But the family is no longer the default next integration target.

Why This Family Was Investigated

The ADT batch family was investigated because:

1. it is already integrity-checkable through tests/validate-adt-batch.sh,
2. it sits close to the direct ADT matching line that still exists in the

maintained solver trees,

1. it extends historical coverage without depending on blocked terrain

recovery, and

1. it looked, at first, like a plausible post-M1 bridge into older direct-ADT

result families.

Preserved Family

Current preserved source of truth:

• data/csp-adt-batch/

Current integrity check:

• tests/validate-adt-batch.sh

The preserved family contains four direct-CSP ADT experiment lines:

Important note:

These ij1-ij4 names are not the same family as the later thesis ij2 / ij3 / ij4 memory-CSP line under Q-Batch-SBCL/.

Preserved Driver Inventory

The preserved archive does not use one driver file per family. It uses a small set of batch-part driver files plus shell wrappers:

Shared preserved facts across those drivers:

1. they all call adt directly,
2. they all use :situation-id "adt-t2-1" and :template-id "adt-t2",
3. they all vary :sit-noise, :random-ident, and :output-file,
4. they all depend on the old load chain rooted in the base csp tree,
5. and the shell wrappers all run from historical /u/sgwoods/csp.

Current State

What is already true:

• the archive structure is preserved,
• the raw result grids are present,
• the historical CI summaries are present,
• the family is automated as an integrity check,
• and the repo now treats it as the next post-M1 bridge.

What is not true yet:

• there is no supported modern rerun workflow for this family,
• there is no normalized qcsp3-era driver for these experiment modes,
• and there is no published equivalence claim between a modern rerun and the

preserved ADT batch summaries.

First Investigation Result

The first narrow executable bridge now exists for one preserved case:

• family: ij2
• case: noise 50, random-ident "default"
• host: csp:adt

Current result:

• the bridge runs successfully through csp:adt,
• it reproduces the expected knob pattern (BT, node consistency on, no AC,

FC, DR, random-ident default, RANDOM ordering),

• but it does not yet reproduce the preserved non-timing metrics.

Current observed divergence versus preserved ij2-050.1:

That means the first bridge is already useful: it has moved the ADT batch family from "pure archive" to "executable investigation," but it has not yet crossed into reproduction.

Investigation Strategy

The safest way to investigate the family was:

1. keep data/csp-adt-batch/ as the preserved historical source,
2. document the experiment-to-search-mode mapping clearly,
3. identify which maintained solver line is the best executable stand-in for

the family,

1. create a modern reproduction harness only after that mapping is stable, and
2. compare modern outputs against the preserved archive without rewriting the

archive itself.

Candidate Executable Mapping

Working hypothesis:

This mapping remains a bridge hypothesis, not a finished validation claim.

Host Comparison Result

For the narrow executable bridge probes, the better maintained host is:

csp/ first, then compare against qcsp3/ later if useful.

Why csp/ is the better first bridge host:

1. the preserved drivers are clearly rooted in the historical base solver tree

(/u/sgwoods/csp) rather than a later integrated line,

1. csp:adt already matches the preserved default IDs

("adt-t2-1" / "adt-t2"),

1. the preserved driver knobs map directly onto the simpler csp:adt

interface without having to neutralize qcsp3-specific defaults,

1. qcsp3:adt adds later integrated-line features and different defaults

(for example the Quilici-oriented defaults and extra override/suppression controls), which make it a stronger long-term target but a noisier first reproduction surface,

1. and a first successful csp bridge will give us a cleaner historical

reference point before we ask whether qcsp3 can stand in for the same family.

That made qcsp3 the better probe host, but not enough to justify folding the family into the integrated line.

Why It Is Now Snapshot-Specific

The current evidence points to a real model split rather than one missing file or one bad random seed:

1. the preserved ADT batch archive remains intact and integrity-checkable,
2. the narrow csp and qcsp3 bridge probes both run, but neither reproduces

the preserved ij2 metrics,

1. the normalized old-dist1-pre-quilici probe makes the fit worse, not

better,

1. the structure probe shows qcsp3 builds a smaller noise layer with the

strongest node-domain squeeze on t2-c,

1. and the generator probe shows that maintained csp/dist1 and

maintained qcsp3/dist1 are different ADT noise models, not the same model with minor drift.

That combination makes the current project stance:

• keep the family preserved and integrity-checkable,
• keep the bridge notes as provenance and explanation,
• but do not require qcsp3 to reproduce this family as part of the

supported integrated baseline.

What Stays Useful

Even with the snapshot-specific classification, the investigation work still matters because it established:

1. where the divergence starts,
2. which maintained line is closer,
3. that old-dist restoration is not the missing key,
4. and that the remaining gap is rooted in a different ADT noise model.

If Revisited Later

If the project chooses to revisit ADT batch integration later, the right question is no longer "can qcsp3 just rerun the family?" It is:

1. should a dedicated legacy-ADT emulation harness exist for this archive, or
2. is the current snapshot-specific classification sufficient for the

gold-standard line?

Concrete Deliverables Already In Place

The useful deliverables from this investigation are now:

1. inventory the preserved ij*.lisp, shell runners, and summary scripts under

data/csp-adt-batch/,

1. map their knobs onto the maintained ADT entry points,
2. define narrow csp and qcsp3 rerun harnesses,
3. isolate random-state, preprocessing, structure, and generator drift,
4. and leave a clear explanation for why the family is being treated as

snapshot-specific.

The current leading suspect is now random-state lineage. The surviving Rnddefault bundles in qcsp-may29-1996/, qcsp3/, qcsp-alex-sep16-1997/, and historical finds/yj-sun/Csp/ are not byte-identical, and the bridge was originally borrowing only the May29 copy. The new tests/investigate-adt-batch-random-lineage.sh probe exists to compare the same ij2 bridge case across those surviving default bundles before we blame the core solver.

Current result from that probe:

That does not prove random lineage is the entire story, but it does move the investigation from "generic random-state suspicion" to a concrete next read: the base csp bridge is much closer when seeded from the surviving qcsp3 default bundle than when seeded from the may29 or alex copies.

Because of that, the narrow bridge probe in tests/investigate-adt-batch-bridge.sh now defaults to the surviving qcsp3/ADT-Random/Rnddefault bundle rather than the May29 copy. The script still accepts PHD_ADT_BRIDGE_RANDOM_SOURCE=... when we want to compare other surviving seed bundles on purpose.

That default change materially improved the first ij2 bridge reading: the bridge still diverges, but it now stays much closer to the preserved archive on NCC, TCC, BT/visited, and FC/DR cost than the earlier May29-seeded probe did.

The next probe also answered a more important question: tests/investigate-adt-batch-input-shape.sh shows that the divergence now starts before search, not inside backtracking. Under the closer qcsp3 seed bundle, the generated bridge input state currently reports:

Those last two values exactly match the bridge line's Dsize and NCC columns (14.0 and 520). That means the remaining mismatch is already present by the time preprocessing finishes. The current highest-value next question is therefore not "why does search branch differently?" but "why does the generated situation / node-consistency surface differ from the preserved ij2-050.1 case?"

tests/investigate-adt-batch-source-drift.sh now compares that same pre-search surface across maintained source/dist variants using the surviving qcsp3/ADT-Random/Rnddefault bundle:

That means the source-definition question is now sharper: although the preserved wrappers look closer to the older csp tree, the maintained qcsp3 ADT setup currently produces a preprocessing surface closer to the preserved ij2 case than either the maintained csp setup or the normalized old-dist1-pre-quilici variant does. The next useful bridge step is therefore no longer "repair old-dist1 and see if that explains the preserved case." That probe now runs and makes the fit worse. The next step is to understand why the maintained qcsp3/dist1 preprocessing surface is still offset from the preserved archive.

That dedicated qcsp3-side runner now exists as tests/investigate-adt-batch-qcsp3-bridge.sh / tests/run-adt-batch-bridge-qcsp3-ij2.lisp. Using the same surviving qcsp3/ADT-Random/Rnddefault bundle, it currently produces:

That does not make qcsp3 a reproduction yet, but it does change the bridge recommendation: the maintained qcsp3 line is now the closer executable host for the first narrow ij2 ADT batch bridge than the maintained csp line.

The strongest next step is no longer "can qcsp3 run the case at all?". It is now "why does qcsp3 still differ on the remaining bounded metrics, especially solution count and the pre-search Dsize / NCC / TCC surface?"

tests/investigate-adt-batch-structure-drift.sh now drills into that pre-search surface directly for maintained csp/dist1 versus qcsp3/dist1. The current result is that the drift is visible in both the generated noise mix and the per-variable node-consistent domains:

Key structural differences from that probe:

• qcsp3/dist1 currently generates 17 fewer noise statements than csp/dist1.
• The largest statement-mix deltas are fewer begin / end noise blocks and

more check noise statements under qcsp3.

• The node-domain squeeze is not evenly distributed. The largest drop is on

t2-c, which falls from 32 candidates under csp to 13 under qcsp3.

That makes the next investigation target much sharper: compare why the maintained qcsp3 path is generating a smaller, differently shaped noise surface for the same random bundle, and why that especially compresses the t2-c candidate domain.

tests/investigate-adt-batch-generator-drift.sh now compares the maintained source definitions directly. It confirms that the preprocessing drift is not just about random-state lineage:

• csp/dist1 and qcsp3/dist1 are different distributions, not just the same

label carried forward. qcsp3/dist1 adds while, increment, and not-equals, increases block, assign, decl, and check weight, and no longer matches the original equal-weight seven-family csp/dist1.

• qcsp3 also changed the generator behavior, not just the weights. It uses

get-line-number / get-specific-line instead of random-position, supports saved-situation reload, names for blocks explicitly, and allows an extra increment branch inside generated loop bodies.

• The normalized old-dist1-pre-quilici probe shows that restoring the old

weight family alone is not enough. The maintained qcsp3 generator semantics still differ materially from the older csp path.

That narrows the post-M1 design choice:

1. either emulate the older csp ADT noise semantics inside a controlled

qcsp3 bridge harness when reproducing ADT batch results,

1. or treat the ADT batch family as snapshot-specific and document the bounded

divergence rather than forcing the modern integrated line to mimic it.

Non-Goal

This bridge does not mean:

• rewriting the preserved historical files,
• moving the archive under qcsp3/,
• or claiming the family is already integrated just because it is now a named

target.

The goal is to turn an integrity-checkable preserved family into the next deliberate integration experiment, with provenance still intact.

This file reviews whether the repository layout makes it clear:

1. what the primary system artifacts are,
2. what defines domains and example generation,
3. what counts as outputs, preserved results, and graphs, and
4. what remains non-tested, non-integrated, or archive-only.

Short answer: the repo is much clearer than it was, but a few mixed-purpose areas still require insider knowledge.

Top-Level Classification

What Is Already Clear

Primary System Artifacts

These are reasonably easy to identify now:

Domain Definitions

Within each solver snapshot, the domain split is mostly legible:

Preserved Results vs Active Validation

This is now understandable at a high level:

Where The Structure Is Still Doing Too Much Work

1. Q-Batch-SBCL/ mixes code, tracked outputs, and scratch data

This directory is useful but not self-evident at a glance because it contains:

• tracked experiment drivers,
• tracked graph scripts,
• tracked comparison PNGs,
• and runtime-generated run directories and extracted graph tables.

The README explains this, but the directory still behaves like both experiments/ and artifacts/ at once.

2. Historical snapshot roots mix source, generated runtime data, and preserved archives

This is especially true in:

• qcsp-may29-1996/
• qcsp-alex-sep16-1997/

For example, qcsp-may29-1996/ contains source files alongside Q-Batch/, NewData* batches, ADT-SituationMar96/, and other embedded historical artifacts. That is historically faithful, but structurally mixed.

One reviewed exception is now explicitly marked in-place: qcsp-may29-1996/Q-Batch/ is a preserved duplicate of data/acl-experiments/, retained for snapshot integrity rather than active use.

3. Root-level legacy helper scripts are easy to overread

Files like:

• run-test4.lisp
• run-test4-may29.lisp
• run-test4-alex.lisp
• run-csp-tests.lisp
• renovate.lisp

are still valuable, but they look more “primary” than they really are. In the current repo they are secondary/manual helpers, not the main supported flow.

4. Some directory names are historically accurate but semantically opaque

Examples:

• Q-Batch-SBCL/
• NewData4a-Batch/, NewData4b-Batch/, NewData5-Batch/
• Q-Batch-Freeze/
• MyBatch/
• artifacts/ inside snapshots

These names preserve provenance, which is good, but they do not explain their role without documentation.

5. historical finds/ is accurate but awkward as a pathname

The name is understandable to humans, but the space in the directory name adds friction for shell work and scripting.

Recommended Classification Model

Going forward, read the repo through these buckets:

A. Supported integrated line

• qcsp3/
• tests/
• Q-Batch-SBCL/
• active status outputs in docs/
• thesis baseline inputs under data/acl-experiments/

B. Reference snapshots

• csp/
• qcsp-may29-1996/
• qcsp-alex-sep16-1997/

C. Preserved result families

• data/csp-adt-batch/
• data/csp-batch/
• data/csp-save-results/
• data/sparc-archive/PrevResults/
• embedded batch trees such as qcsp-may29-1996/NewData4b-Batch/

D. Archive recovery / provenance intake

• incoming/
• historical finds/
• data/motors-releases/
• data/motors-backups/
• data/lost-datasets.md

E. Manual compatibility helpers

• root run-test4*.lisp
• run-csp-tests.lisp
• renovate.lisp

Recommendations

Low-risk, do-now documentation moves

1. Keep REPOSITORY-STATUS.md and this file linked from README.md.
2. Keep DOCS-COVERAGE-REVIEW.md current as the explicit record of what is

now well-covered versus still thin.

1. Add one short top-level note in README.md that root run-test4*.lisp,

run-csp-tests.lisp, and renovate.lisp are manual compatibility helpers.

1. Add one short note in snapshot READMEs clarifying which subdirectories are:

source, runtime-generated data, preserved results, and archive/context.

1. Keep all new finds landing in incoming/ first, then promote them only

after review.

Medium-risk, defer-until-worth-it structure moves

1. Consider an eventual rename or alias scheme for mixed workspaces such as

Q-Batch-SBCL/ only if the historical name stops paying its way.

1. Consider a future manual/ or compat/ home for root helper scripts, but

only if that does not break established references or provenance.

1. Consider a future no-space alias for historical finds/ if automation

pressure grows.

Do not do casually

1. Do not flatten embedded historical batch trees out of snapshot directories

just to make the layout prettier.

1. Do not rename historically meaningful directories like NewData4b-Batch/

unless the repo adds a carefully documented alias/mapping layer.

1. Do not mix archive-intake material into the supported integrated line

without first promoting it through validation/provenance work.

Bottom Line

The repository already tells a coherent story if you know where to start: qcsp3/, tests/, Q-Batch-SBCL/, data/, and the roadmap files.

What remains structurally confusing is not the solver core. It is the historical overlap between:

• source vs embedded results inside snapshot roots,
• tracked experiment infrastructure vs generated outputs,
• and manual compatibility helpers vs supported workflows.

That means the next best improvements are documentation and labeling, not aggressive directory surgery.

This file records the current state of documentation coverage across the repo:

1. what is already well explained,
2. what still needs insider knowledge,
3. and what the next documentation passes should target.

Use it as the documentation-focused counterpart to:

• REPOSITORY-STATUS.md
• REPOSITORY-STRUCTURE-REVIEW.md
• WORKFLOWS.md

Current Read

Short answer:

documentation coverage is now strong for the primary solver line, the validation spine, the main preserved result families, and the major historical snapshot workspaces.

What remains thinner is no longer the core architecture. It is mostly:

• a few deeper archive/context subtrees,
• some historical/tooling side areas that are preserved but not central,
• and in-code/operator explanation depth inside specific Lisp files rather than

top-level repo navigation.

Coverage Levels

Strong

These areas now explain themselves clearly either in place, from the top-level docs, or both:

Good But Still Mixed

These areas are understandable, but still rely on historical naming or mixed contents that no amount of README text can fully hide:

Still Thin

These are the most likely next documentation targets if we keep going:

What Improved In This Pass

The biggest change over the recent cycles is that the repo no longer relies on tribal knowledge for:

1. intake versus historical-provenance flow,
2. snapshot-local AO layers,
3. snapshot-local batch/workspace trees,
4. working-state random/situation directories across the solver lineage,
5. and the generated handbook/public readable copy as the main human-friendly

overview.

That is a real shift from "the docs exist if you know where to look" to "the repo can orient a new reader from several likely entry points."

Main Remaining Risks

The largest documentation risks now are subtle rather than catastrophic:

1. a reader may still overread preserved batch/result trees as supported active

workflows just because they sit inside snapshot roots,

1. a reader may still overread root helper scripts as primary entry points,
2. and the large archive-heavy trees may still feel deeper than their

supporting narrative.

Those are now "clarity polish" risks more than "the repo is unreadable" risks.

Recommended Next Documentation Moves

If the project keeps investing in the 0.3.x documentation lane, the best next steps are:

1. deepen qcsp-alex-sep16-1997/testdata/ result-family guidance,
2. add one small pass over the archive-only historical finds/ subtrees that

still feel opaque,

1. continue in-code docstrings/operator guidance in the most-used maintained

solver files,

1. and only then consider whether the root helper scripts need structural

relocation rather than more explanation.

Maintenance Rule

Update this file whenever:

1. a previously confusing subtree gains a local guide,
2. the handbook adds a significant new coverage layer,
3. a mixed workspace becomes materially clearer or materially more confusing,
4. or the recommended next documentation targets change.

This file records historical data and files that have been reviewed for redundancy.

Its purpose is to separate two different cases clearly:

1. Reviewed duplicate / redundant for the active main project

The repo already has a canonical copy elsewhere, and the duplicate is kept only for snapshot integrity or provenance.

1. Looks duplicate, but still has go-forward value

The material overlaps another tree, but still matters for lineage, historical context, or recovery work.

Status Key

• Canonical elsewhere: do not treat this copy as the active source of truth.
• Retain for provenance: keep it, but do not build new supported workflows on it.
• Still go-forward valuable: overlapping material still has a distinct role.

Reviewed Items

Practical Rule

If a reviewed duplicate is needed for:

• snapshot integrity,
• thesis/result provenance,
• or archive-recovery explanation,

keep it, but mark its canonical active counterpart clearly.

If it is a true duplicate for day-to-day supported workflows, point users to the canonical location and avoid expanding the supported validation flow around the duplicate copy.

Current Canonical Copy Rules

1. For the active ACL thesis-result baseline, prefer data/acl-experiments/

over qcsp-may29-1996/Q-Batch/.

1. For the active preserved ff* lineage, treat

qcsp-may29-1996/NewData4b-Batch/ and data/sparc-archive/PrevResults/ff* as paired provenance layers rather than competing duplicates.

1. For archive intake under historical finds/, do not assume exact-match

overlap means “safe to discard.” Many such copies still help explain how the tracked snapshot was assembled.

Maintenance Rule

Update this file whenever:

1. a new duplicate tree is positively identified,
2. a canonical active copy is chosen for a preserved family,
3. an archive overlap is reviewed and judged to still have provenance value, or
4. a previously ambiguous overlap is reclassified as truly redundant.

This document describes the migration of the PhD research codebase from Allegro Common Lisp (SPARC, 1993-1997) to Steel Bank Common Lisp (macOS ARM64, 2026).

Overview

Four systems were modernized covering 49 source files:

• :phd-research (csp/) -- base CSP solver
• :qcsp3 (qcsp3/) -- extended solver with memory-CSP and Quilici search
• :qcsp-may29-1996 -- historical snapshot (May 1996)
• :qcsp-alex-sep16-1997 -- historical snapshot (Sep 1997)

What Changed

Build system

Replaced Allegro CL's manual load chains with ASDF system definitions. Each system got a package.lisp with defpackage/in-package, isolating symbols into their own packages instead of polluting CL-USER.

Franz-isms removed

• excl:* and sys:* calls (Allegro-specific extensions)
• #p(...) reader macros (Allegro pathname literals)
• .clinit.cl initialization files
• Hardcoded Mac OS 9 paths ("Macintosh HD:Languages:...")

Dead code removed

• Backup artifacts (.bkp, .bak, *~ files)
• Mac OS 9 code branches and path logic
• Duplicate/unreachable function definitions
• .DS_Store files

Bug fixes found during renovation

These are latent bugs in the original code that were discovered and fixed:

Return value normalization

Changed 'complete, 'error, 'time-bound (package-internal symbols) to :complete, :error, :time-bound (keywords) across all four bt.lisp files. Keywords are self-evaluating and package-independent, making cross-package test assertions reliable.

Warning suppression

SBCL emits redefinition-warning when a function is defined in one file and intentionally redefined in another (e.g., mpr-simple.lisp defines stubs that mpr-setup.lisp overrides). Added sb-ext:muffle-conditions declarations around the 16 files that participate in this pattern, bringing the warning count from ~60 per system to 0.

What Did NOT Change

The core algorithms are untouched:

• Backtracking search with chronological and intelligent backjumping
• Forward checking (FC) and dynamic variable rearrangement (DR)
• AC-3 arc consistency
• Advance sort heuristic
• Memory-CSP two-phase search (index + resolution)
• Quilici similarity-based retrieval
• Template and situation data structures
• All CSP constraint formulations

This was verified by running the same experiment (ij2, noise=50, seed=default) on both the pre-cleanup and post-cleanup code. The results were identical:

            Pre-cleanup    Post-cleanup
NCC         284            284
TCC         281            281
BT          38             38

Verification

Unit tests

FiveAM test suites cover all four systems:

sbcl --non-interactive --load "tests/run.lisp"

Integration tests

Arc-oriented (AO) solver integration tests:

sbcl --non-interactive --load "run-test4.lisp"
sbcl --non-interactive --load "run-test4-may29.lisp"
sbcl --non-interactive --load "run-test4-alex.lisp"

Experiment replication

Three experiment series compare CSP search efficiency under increasing noise (50-1000 extraneous program statements), each with 20 noise levels and 10 random seeds (200 runs per series):

Experiments were run across all four code snapshots:

# qcsp3 (primary)
bash Q-Batch-SBCL/ij2.sh && bash Q-Batch-SBCL/ij3.sh && bash Q-Batch-SBCL/ij4.sh

# alex (Sep 1997 snapshot)
bash Q-Batch-SBCL/run-alex-all.sh

# may29 (May 1996 snapshot)
bash Q-Batch-SBCL/run-may29-all.sh

Results are compared against the original Allegro CL runs (now stored in data/acl-experiments/) using 95% confidence intervals. The CI bands overlap at every noise level for all three series across all snapshots, confirming algorithmic equivalence despite different random number generators (ACL's proprietary PRNG vs SBCL's Mersenne Twister).

python3 Q-Batch-SBCL/Graph/compare-all-overlay.py    # Generate 4-way plots (requires matplotlib)

Comparison plots are in Q-Batch-SBCL/Graph/compare-*-overlay.png. Each plot shows four series: ACL (SPARC), SBCL qcsp3, SBCL alex, and SBCL may29.

Key experimental findings

• ij2/ij3: All four series (ACL, qcsp3, alex, may29) track closely with overlapping CI bands, confirming algorithmic equivalence across all snapshots.
• ij4: The alex snapshot diverges sharply upward (~6x higher TCC than the others). Root cause: Yongjun Zhang simplified the ts-matches-type function in alex's adt-simple.lisp (line 1296), commenting out the detailed type-matching logic (Decl array/range checking, parameter-count matching for Zero/Assign/Print/Check/Increment/Not-Equals). The simplified version only checks statement type name equality, which allows more domain values to survive node consistency:

The causal chain: simplified ts-matches-type → ~1.6x larger domains → ~4x more backtracks → ~6.5x higher TCC. This was intentional — the simplified NC was likely paired with alex's DFA-based features (node-type-consis, dfa-rearrangement) which would compensate, but those features default to nil and are not enabled in the standard ij4 experiments. A diagnostic script at Q-Batch-SBCL/diagnose-ij4.sh reproduces these results.

Batch experiment issues encountered and resolved

DataFind Archive Audit

The data/sparc-archive/ directory (formerly DataFind/) contains .dir files — original directory listings from the SPARC archive. An audit compared these against the current repo:

Files consistently missing across all snapshots (compile.lisp, compile-set.lisp, load.lisp) are old ACL build infrastructure superseded by ASDF. The package.lisp files added during renovation are consistently "extra" (expected).

Remaining Work

See GitHub Issues for tracked items. Summary:

Completed

1. ~~Clean up alex snapshot~~ — Done: 34 non-core .lisp files moved to extras/, 15 result/output files moved to artifacts/, 7 ephemeral files deleted, 83 generated seed files untracked. README added. (Issue #1)
2. ~~Investigate alex ij4 divergence~~ — Done: root cause is simplified ts-matches-type in alex's adt-simple.lisp (detailed type-matching commented out by Yongjun Zhang). This was intentional, paired with DFA-based extensions not enabled in standard experiments. Diagnostic script at Q-Batch-SBCL/diagnose-ij4.sh. (Issue #2)
3. ~~Recover missing files~~ — Done: csp/unify.lisp recovered from qcsp-may29-1996/Keep/ with defconstant→defparameter fix. adt-test2.lisp, adt-test3.lisp, gsat-test.lisp are truly lost (not in any snapshot). compile-set.lisp superseded by ASDF. (Issue #3)
4. ~~Untrack remaining generated data~~ — Done: all ADT-Random/ and ADT-Situation/ directories across all four systems are untracked and in .gitignore. (Issue #7)

1. ~~Clean up DataFind/~~ — Done: documented PrevResults, organized archives, created DataFind/README.md. Later consolidated into data/sparc-archive/. (Issue #5)
2. ~~Expand test coverage~~ — Done: added TCC/NCC/BT regression assertions to 25 tests across 4 suites. Standard and confused queens get exact metrics; ADT/MPR get exact NCC + TCC ceilings. (Issue #6)
3. ~~CI/CD~~ — Done: GitHub Actions workflow at .github/workflows/test.yml runs all FiveAM suites on push/PR. (Issue #8)

Open

1. Investigate QCSP-nov96 — intermediate snapshot with unique terrain analysis code not in repo. Three source files remain unrecovered in the working tree (terrain-setup.lisp, terrain-simple.lisp, closure.lisp), but a newly identified Lacie1 historical drive reportedly contains terrain data and the generator. Recovery is no longer just a generic backup-media search; the next concrete step is to sort that drive and compare it against QCSP-nov96.dir. See data/lost-datasets.md. (Issue #4)

Next Phase Roadmap

Guiding principle for the next phase: treat the published PhD thesis results, the preserved historical experiment artifacts, and the current regression suites as the foundation for every future change. New work should either preserve those published behaviors or explain any intentional deviation in a repeatable way, with the long-term aim of converging on one gold-standard code line rather than maintaining several disconnected runnable snapshots forever.

Goal And Current Position

Overall project goal

Bring the thesis codebase to a state where:

1. the integrated constraint solver reproduces the PhD-reported results from a

fresh checkout,

1. the other historical domains and reported result families are either

executable, integrity-checkable, or explicitly classified as provenance-only,

1. one gold-standard code line can stand in for the historical solver lineage

with snapshot-specific differences documented, and

1. new research can branch from that validated baseline with any deltas

measured and explained.

In short: turn the renovated snapshots, preserved data, and recovered archives into one trustworthy integrated research platform, not just a modernized copy of legacy Lisp.

Current subgoals

For the current phase, the practical subgoals are:

1. keep the supported validation spine green from a fresh checkout,
2. keep widening the validated umbrella beyond the main thesis ij2/ij3/ij4

path,

1. reduce warning noise enough that validation logs act as a reliable

regression signal,

1. make the historical result families legible enough that they can be judged

for eventual inclusion under one integrated solver line, and

1. define the first concrete milestone that qcsp3/ would have to satisfy to

earn "gold-standard" status.

Where we are against that goal

First qcsp3/ integration milestone

The first concrete milestone for qcsp3/ is:

Milestone M1: integrated validated baseline

qcsp3/ can be treated as the project's first real integrated solver line when all of the following are true:

1. the current validation spine passes from a fresh checkout:

tests/run.lisp, tests/validate-artifacts.sh, tests/validate-ao.sh, and tests/validate-ff-provenance.sh,

1. qcsp3/ remains the default executable path for the supported

thesis-result story, especially the ACL-vs-SBCL ij2/ij3/ij4 comparison workflow,

1. the supported AO baseline is asserted and documented as part of the

integrated line rather than treated as a separate historical annex,

1. the preserved ff1/ff2/ff3 family has an explicit documented

relationship to the integrated line, even if that family is still integrity-checkable rather than fully rerunnable through qcsp3/, and

1. any remaining meaningful differences between qcsp3/ and the reference

snapshots are documented as intentional, bounded, or still-open gaps.

The active delta list for this is now centralized in INTEGRATION-DELTAS.md. The short gate-by-gate answer that supported the M1 decision now lives in M1-READINESS.md.

M1 is intentionally narrower than a final "gold-standard achieved" claim. It does not require every historical family to be fully executable through qcsp3/ yet. It does require that qcsp3/ become the clear operational center of the validated baseline, with the historical snapshots serving as reference anchors rather than co-equal supported workflows.

Current roadmap position

• Phase 1 / 0.1.x Stability: effectively complete for the supported

artifact pipeline. Fresh-checkout plot regeneration and artifact validation are in place.

• Phase 2 / 0.2.x Verification: effectively complete for the M1

baseline. This phase delivered stronger regression assertions, AO asserted coverage, automated thesis-comparison checks, ff* integrity/provenance validation, and incremental warning cleanup.

• Phase 3 / 0.3.x Documentation: complete enough for 1.0.0. High-level

docs are much stronger, the code/test/results roots are easier to navigate, and the status/handbook/public artifacts are now part of the release flow.

• Phase 4 / Research Readiness: not yet active as the main lane. We have

diagnosed alex's ij4 divergence, but we are intentionally holding off on broader experimental changes until the baseline is tighter.

• Phase 5 / Archive Recovery: active in parallel. The historical finds/

intake is now classified, yj-sun/Csp has loader/result provenance notes, and archive-to-PrevResults mapping has begun. This lane is now supporting integration planning, not just intake triage.

Recommended next steps

1. Keep the current validation spine green: tests/run.lisp,

tests/validate-artifacts.sh, tests/validate-ff-provenance.sh, and tests/validate-ao.sh remain the merge gate for the supported baseline. Keep REPOSITORY-STATUS.md, REPOSITORY-STRUCTURE-REVIEW.md, and DOCS-COVERAGE-REVIEW.md in sync as the broader repo surface changes.

1. Make incoming/ intake, de-duplication, and categorization the next major

work lane. New materials are likely to be the main source of project movement after 1.0.0, so keep the intake, promotion, duplicate review, and archive classification flow disciplined.

1. Target 1.0.1 for STYLE-WARNING cleanup outside the supported release gate,

especially the remaining gsat lexical-special warnings and legacy helper path warnings.

1. Treat the documentation lane as maintenance now: keep adding selective

clarifications when useful, but focus on keeping the docs/handbook/status surface accurate rather than broad new README waves.

1. Keep the ADT batch ij1-ij4 archive family integrity-checkable and

documented, but treat it as snapshot-specific for now rather than as a required post-M1 integration target. The investigation note for that family lives in ADT-BATCH-INTEGRATION.md. Current recommendation: preserve the bridge probes and the explanation of the maintained csp / qcsp3 noise-model split, but do not require the integrated line to reproduce this family.

1. Keep the supported validation gate clean and high-signal; treat new warning

output in tests/run.lisp or tests/validate-ao.sh as regression noise to investigate, not normal background.

1. Keep building out the validation matrix when useful, but with the main

archive-heavy families now mapped or integrity-checked, avoid widening the supported umbrella casually without a clear post-1.0.0 or intake-review benefit.

1. Only after the baseline, warning surface, provenance work, release

maintenance, and intake flow are tighter, begin controlled integration and research-readiness experiments such as alex DFA-option isolation against the validated snapshot.

1. Treat Hanoi-4 explicitly as a phased lane: for 1.x, keep a clear record

of the situation, artifacts, and any ingested references; for 2.0, pursue actual behavioral/repeatability understanding once the material exists. Seed that future analysis with later Towers of Hanoi encoding literature such as Martins and Lynce (2008), which may help frame hierarchical setup, problem encodings, and repeatability questions more productively than the original 1998 context alone.

Phase / Release Alignment

Keep the repo on 0.x releases until the thesis-validation baseline is stable enough that a fresh checkout can reproduce the supported historical results and the docs accurately describe that supported path.

• 0.1.x Stability builds: artifact paths, reproducible plot generation,

and baseline environment setup.

• 0.2.x Verification builds: stronger asserted regression coverage around

the thesis-era baselines. This milestone track now culminates in accepted M1.

• 0.3.x Documentation / research-readiness builds: clearer operator docs,

explicit supported workflows, and guarded extension points for new research.

• 1.0.0 released: phases 1-3 are complete, CI continuously validates the

supported thesis-result baseline, release notes can describe deviations from the thesis as intentional rather than accidental, and deferred lanes like Hanoi-4 are clearly documented rather than silently unresolved.

• 1.0.1 target: keep the 1.0.0 baseline stable while reducing the

remaining STYLE-WARNING noise outside the supported release gate and keeping newly ingested material classified cleanly.

• 2.0.0 target: the integrated line is stable enough to absorb deeper

historical/research-readiness questions, including explicit behavioral and repeatability analysis for lanes like Hanoi-4.

Increment the internal build number once per completed roadmap cycle and note the owning phase in the release summary so future work stays tied to the plan.

Phase 1: Stability

1. Keep the artifact pipeline executable from a fresh checkout. The repo should

always be able to regenerate CI summaries and comparison plots from the checked-in ACL and SBCL experiment artifacts.

1. Reduce the remaining warning noise during normal loads so new regressions are

easier to spot. Treat a quieter load/test log as a reliability feature, not cosmetic cleanup.

Phase 2: Verification

1. Strengthen regression coverage around deterministic baselines, starting with

confused-queens metric assertions and other low-risk cases where exact behavior can be pinned down.

1. Finish converting the AO/test4 path into supported asserted coverage. CI now

checks qcsp3 and may29 AO cases 1-3 across the reduction families, retains the legacy test4s/test4a wrappers, and keeps alex's revise baseline in the supported AO line. That bounded AO surface now supports the accepted M1 call without pretending the full historical AO space is already unified.

1. Keep the thesis-era versus modern results comparison executable. CI now

checks that regenerated SBCL ij2/ij3/ij4 tables preserve the ACL baseline ordering, correlation, and bounded ratio bands; next work should connect the older PrevResults/ff*.ci family once the exact experiment mapping is recovered.

Phase 3: Documentation

1. Add docstrings and targeted explanations to the core entry points and major

algorithms so future work can build on a clearer map of the code.

1. Keep the top-level docs synchronized with the actual executable state of the

repo, especially around CI coverage, warning state, and experiment tooling.

Phase 4: Research Readiness

1. Explore alex's DFA-related options (node-type-consis,

dfa-rearrangement) in isolated experiments to determine whether they close the known ij4 gap without disturbing the validated baseline path.

1. Define a repeatable workflow for post-renovation research: establish the

baseline snapshot, rerun validation, record deltas against thesis-era results, and only then evaluate new hypotheses or extensions.

Phase 5: Archive Recovery

1. Continue the historical recovery track by unpacking/cataloging the legacy

compressed archives and keeping watch for any media that could restore the lost QCSP-nov96 terrain code and data, with Lacie1 now recorded as the strongest recovery lead pending review.

1. Treat newly recovered material under historical finds/ as archive intake,

not baseline code. The current intake appears to split into: yj-sun/Csp as a likely solver-lineage recovery candidate, yj-sun/Gen++ as a likely upstream analyzer-generation toolchain, and Unravel/ / Refine/ as adjacent program-understanding context that should stay reference-only until a direct thesis-validation role is proven.

1. Prioritize archive work that strengthens the validated research story:

first compare historical finds/yj-sun/Csp against the current snapshots and experiment artifacts, then map any unique batch/results material to the thesis-era PrevResults/ff*.ci family, and only after that spend time on broader adjacent-tool recovery.

Commit History

959dd69  BASE: Original Allegro CL PhD source and publications
b6761e8  Modernize legacy ACL project for SBCL with ASDF build system
a905d9b  Modernize qcsp-may29-1996 and qcsp-alex-sep16-1997 for SBCL
ffbeb16  Add test4 runner and fix missing rfn variable in qcsp3
2f37012  Add test4 runners for qcsp-may29-1996 and qcsp-alex-sep16-1997
764e19e  Add csp test runner and fix queens arc-consis value
38d181a  Add Q-Batch-SBCL experiment infrastructure for SBCL replication
15aadf8  Fix ij4 output paths and add data extraction/comparison pipeline
83f4a54  Add README, FiveAM tests, entry point, and cleanup dead code
78facc4  Add defpackage/in-package to csp/ and qcsp3/ systems
e1b6c18  Fix LENGTH variable bug in bm.lisp and *current-situation typo
3918f1f  Remove dead files, backup artifacts, and Mac OS 9 code branches
89552a1  Modernize older snapshots and remove Mac OS 9 dead code
d8b8650  Add FiveAM tests for older snapshots and fix latent bugs
992fb02  Normalize return keywords, fix MPR bugs, muffle redefinition warnings
48d6607  Add ACL vs SBCL comparison plots and seed generator
b8ea6d4  Add renovation docs, expand tests, fix output-file concatenation bug
c780cc5  Re-run ij3 and ij4 experiments fresh with regenerated seeds
afe6666  Add date/time and git version stamp to comparison plots
88da35f  Fix alex ADT/memory-search by restoring Quilici data and polymorphic accessors
2427d96  Restore alex noise injection and run batch experiments
80d72c6  Add may29 batch experiments, 4-way comparison plots, and consolidate gitignore
ff95fae  Update README and RENOVATION docs with may29 results and .dir audit
f4c4d51  Clean up alex snapshot and recover unify.lisp
0474e79  Update docs to reflect alex cleanup and closed issues
fdd5ceb  Replace MvSit2.tar.Z with extracted ADT situation files
09a0d3b  Clean up may29 snapshot and fix test4 runner paths
76df23d  Clean up qcsp3 snapshot and untrack generated MPR situation data
251fc6f  Document alex ij4 TCC divergence root cause (Issue #2)
188e4a6  Add TCC/NCC regression assertions and GitHub Actions CI
afa377f  Fix CSP MPR test failure on CI — create MPR-Situation directory
7ff62ff  Document DataFind/ archive structure (closes #5)
a0de660  Consolidate all datasets into normalized data/ directory