light-project-structure

# Project structure lifecycle

Own the **visible project tree** and its migration evidence. Do not mistake a
tidy directory for reproducible research.

Read
[`references/project-lifecycle-resource-map.md`](references/project-lifecycle-resource-map.md)
before an existing-repository migration. It defines artifacts, policy, access
levels, provenance, and cross-skill ownership. Use
[`references/structure-profiles.json`](references/structure-profiles.json) for
small profile minima and
[`templates/project-policy.template.json`](templates/project-policy.template.json)
for explicit project/file policy.
Use `scripts/structure_governance_gate.py` before delivery to validate profile
choice, existing-project read-only safety, template residuals, secret scan,
environment doctor, authorization binding, applied-manifest binding, and
rollback evidence.

## Non-negotiable boundary

1. Treat inventory as read-only access, not authorization to move.
2. Never overwrite, delete, run `git rm --cached`, initialize DVC, rewrite
   configuration, or move a symlink automatically.
3. Never use `--force` as consent. The lifecycle has no force bypass.
4. Preserve all `.light/` content. `memory-pm` alone creates or edits passport,
   project card, decision log, version history, terminology, and handoff files.
5. Keep absent facts `UNKNOWN`. A path such as `data/raw` does not prove size,
   sensitivity, immutability, recomputability, or Git policy.
6. Do not turn this overlay into a DAG node. Emit no `light.findings.v1`; add no
   `STAGE_GATES`, `ROUTES`, stage number, or back-edge.
7. State that structural conformance does not prove data quality, experiment
   reproducibility, statistical validity, or paper quality.
8. Never ship a generated or migrated tree with unresolved template placeholders,
   unhandled secret-scan hits, or missing required Python/R/environment checks.

## Choose the mode

| Situation | Mode |
|---|---|
| Empty target and the user wants a starting tree | `scaffold` with one explicit profile |
| Existing repository, monorepo package, or non-Git directory | `intake`, then stop at the decision |
| User approved exact moves after seeing the plan | create authorization, then `apply` |
| Applied moves need reversal | `rollback` from the applied manifest |

Do not scaffold a non-empty directory. Do not retrofit a fixed 23-directory
tree onto R, paper-only, mixed-language, custom, or monorepo projects.

## Phase 1 — Intake and requirements

Collect or preserve as `UNKNOWN`:

- project type and whether the selected root is a Git root, monorepo subroot, or
  non-Git directory;
- deliverables, compute environment, data volume, remote storage,
  collaborators, CI, license, and retention;
- Git root, branch, tracked/untracked/ignored state, uncommitted changes,
  submodules, symlinks, large files, and sensitive path signals.

Choose the smallest profile after inspecting observed technology signatures and
the user's declared deliverables:

- `python-research`
- `r-research`
- `mixed-research`
- `paper-only`
- `existing-custom`

Profiles are extensible minima, not compliance verdicts.
The selected profile is not evidence about the project. `intake` records
observed file/config signals separately from policy-declared artifact types,
recommends a profile, and fails the governance gate when a different profile
has no concrete `profile_selection_reason`.

Copy the policy template outside the source root, fill known project facts, and
add file rules only where there is evidence. Legitimate tracked artifacts
include small public fixtures, reviewed golden files, DVC pointers, final paper
figures, release artifacts, or audit evidence when project policy requires
them. Large/sensitive source data, models, and results usually need DVC/object
storage, but require a decision rather than a directory-name verdict.

Run:

```text
python scripts/scaffold.py intake <root> --out <evidence-dir> \
  --profile mixed-research --policy <project-policy.json>
```

The command writes evidence to `--out` and verifies that the source snapshot
and Git status did not change.

`intake` also emits technology signatures, the environment doctor, template
residual scan, secret scan, and governance report named in the resource map.
Tool checks derive from observed or explicitly declared artifact types, not
from the chosen profile alone. If the project requires Python, R, Quarto, DVC,
LaTeX, or other local tools, record those requirements in the policy. Use the
standalone doctor command only when you need an extra ad-hoc check:

```text
python scripts/structure_governance_gate.py --doctor python r
```

## Phase 2 — Review the dry-run

Read the intake artifacts named in the resource map. Check:

- every inventory row has locator/hash/size/Git state plus explicit or
  `UNKNOWN` owner, producer, recomputability, sensitivity, classification,
  target, and policy basis;
- technology signatures identify their locator and distinguish observed
  evidence from `policy.project.artifact_types`; the selected profile matches
  the recommendation or has a concrete user override reason;
- duplicates are evidence, never auto-delete instructions;
- symlinks, existing targets, and many-to-one moves are blocked;
- `../`, absolute, drive-letter, UNC, or otherwise root-escaping action paths
  are blocked in the dry-run plan and governance gate, not deferred to apply;
- a monorepo subroot uses paths relative to that subroot without treating the
  whole Git root as its project;
- `.light/` is preserved and has no move action;
- large tracked fixtures are not condemned merely for being under `raw`;
- large recomputable or sensitive artifacts surface a storage-policy decision.
- template provenance, residual placeholder scan, secret scan, and environment
  doctor are present when relevant; `.env` ignore is not a secret-scan result.

Present:

1. the recommended profile and why;
2. safe action IDs;
3. blocked conflicts and unknowns;
4. separate decisions for move/rename