Skip to content

chore: Makefile target + docs for akta reconstruct on the example release #13

Description

@fraware

Context

AS-08 added akta reconstruct and institutional docs (docs/RELEASE.md, docs/operator_pilot_guide.md, docs/integration_guide.md). The reconstructable demo is available via make demo-reconstructable (writes under dist/), and there is a checked-in tree at examples/reconstructable_experiment/. Contributors still lack a single, low-friction Makefile entry that runs akta reconstruct against a known local release path and is documented next to the CLI examples—so the reconstruct path is harder to discover than other demo targets.

Goal

Add a small Makefile target (and a short docs mention) that runs akta reconstruct on a documented example/release directory and prints or writes a reconstruction report newcomers can inspect.

Suggested work

  1. Add a Makefile target such as reconstruct-example (name can vary) that:
    • Invokes akta reconstruct --release <path> --out <report.json> (or equivalent documented flags).
    • Uses either examples/reconstructable_experiment/ or the output of make demo-reconstructable under dist/reconstructable_experiment/—pick whichever path actually validates cleanly today; if the checked-in example needs a thin README note about regenerating via the demo, say so.
  2. Document the target in docs/RELEASE.md (reconstruction checklist) and/or docs/operator_pilot_guide.md / docs/integration_guide.md beside existing akta reconstruct snippets.
  3. Ensure the target is listed in .PHONY if that is the Makefile convention.
  4. Keep the change tiny: no new packaging features, no cross-repo SCOPE requirements.

Out of scope

  • Changing reconstruct library semantics.
  • Making ci / ci-pilot depend on the new target unless maintainers explicitly want that (default: keep it optional/manual).
  • Fixing unrelated stale example artifacts beyond what is required for the target to succeed (if large, open a follow-up).

Acceptance criteria

  • make <target> runs successfully on a clean clone after install and (if required) make demo-reconstructable.
  • Docs show the Makefile command next to the CLI reconstruct example.
  • Reconstruction report indicates success (ok=true or equivalent documented field) for the chosen path.
  • No dependency on an external SCOPE checkout.

Suggested files

  • Makefile
  • docs/RELEASE.md and/or docs/operator_pilot_guide.md / docs/integration_guide.md
  • Possibly a one-line note under examples/reconstructable_experiment/reconstruction_report.md

How to test

\\�ash
pip install -e ".[dev,security]"

if the target depends on generated dist artifacts:

make demo-reconstructable
make reconstruct-example # or the chosen target name
\\

  • Open the written reconstruction JSON/report and confirm bindings/checksums look populated.
  • Optionally: pytest tests/test_as08_reconstruct.py -v to ensure library/CLI tests remain green.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions