chore(project): adopt Specification 1

.gitattributes

@@ -0,0 +1,2 @@
+/project.yaml text eol=lf -filter -ident -working-tree-encoding
+/vendor/project-manifest/** -text -filter -ident -working-tree-encoding

.github/workflows/verify.yml

@@ -0,0 +1,36 @@
+name: verify
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Prepare contributor Python
+        id: python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13.16"
+      - name: Prepare Git build prerequisites
+        run: sudo apt-get update && sudo apt-get install --no-install-recommends -y build-essential zlib1g-dev
+      - name: Prepare checksum-bound Git 2.56
+        id: git
+        env:
+          PREPARED_PYTHON: ${{ steps.python.outputs.python-path }}
+        run: '"$PREPARED_PYTHON" -I -S -B scripts/prepare-ci-git.py'
+      - name: Verify source and revision declaration
+        env:
+          PREPARED_PYTHON: ${{ steps.python.outputs.python-path }}
+          PREPARED_GIT_BIN: ${{ steps.git.outputs.git_bin }}
+          SHELLTUTOR_MANIFEST_REV: ${{ github.sha }}
+        run: |
+          export PATH="$PREPARED_GIT_BIN:$PATH"
+          make verify PYTHON="$PREPARED_PYTHON"

AGENTS.md

@@ -3,8 +3,8 @@ title: shelltutor Agents Contract
 category: governance
 component: agents-contract
 status: active
-version: 0.1.0
-last_updated: 2026-07-14
+version: 0.2.0
+last_updated: 2026-10-17
 tags: [agents, claude, codex, authority, boundary]
 priority: high
 ---
@@ -69,7 +69,9 @@ operator-named comments).
   network access, privilege handling, sandbox boundaries) only when the
   user request clearly calls for it.
 - **Restricted work** — Do not introduce dependencies that require
-  installation outside `bash` and a standard POSIX userland; do not access
+  installation outside `bash` and a standard POSIX userland in the learner
+  runtime. Contributor-only declaration validation uses prepared Python 3.11+
+  and Git 2.56+ as documented below. Do not access
   files outside this repository during normal operation; do not perform
   account, billing, or credential changes.
 
@@ -90,6 +92,21 @@ When authority is unclear, ask before acting.
 
 ## Validation
 
+- `make verify` is the contributor source gate. It includes the offline
+  Specification 1 declaration check and its regression tests, followed by the
+  existing static checks, optional ShellCheck and smoke checks. It installs
+  nothing. `scripts/verify-project.sh` is its no-argument manifest entrypoint.
+- Adoption: root `project.yaml` follows Specification 1, with repo-owned
+  immutable Release 1 binding from `jefahnierocks/project-manifest`; see
+  [the binding and contributor workflow](docs/project-manifest.md). No parent
+  release pin or global runtime default is inherited.
+- Keep the vendored release and separate bootstrap byte-exact; never format,
+  patch or import them before the consumer verifies their independent pins.
+- A declaration verdict does not prove tutor portability, native gate success,
+  producer admission or runtime acceptance. Local no-argument validation reads
+  tracked working bytes; CI also selects the exact commit with
+  `SHELLTUTOR_MANIFEST_REV`. That selector does not turn the native gate into
+  a historical-source execution.
 - Run the tutor (`./shelltutor`) and complete at least the lesson surface
   affected by a change.
 - For portability changes, validate on both Linux and macOS when possible,

CONTRIBUTING.md

@@ -3,8 +3,8 @@ title: shelltutor Contributing
 category: process
 component: contributing
 status: active
-version: 0.1.0
-last_updated: 2026-07-14
+version: 0.2.0
+last_updated: 2026-10-17
 tags: [contributing, verification, change-discipline]
 priority: medium
 ---
@@ -33,16 +33,17 @@ implying success.
 
 ## Quality Gates
 
-The quality gates are wrapped in `Makefile` and run locally without external
-infrastructure (CI activation is deferred per the GitHub Posture section
-below). The intent is a one-command pre-commit verification for
-contributors.
+The quality gates are wrapped in `Makefile` and run locally without network
+access or tool installation. Prepare contributor Python 3.11+ and Git 2.56+
+first; `make verify` refuses unavailable declaration prerequisites. CI runs the
+same gate on every push and pull request. The learner runtime remains Bash-only.
 
 ```bash
 make check       # FF-001 + FF-002 + FF-004 + FF-007 static analysis (always runs)
 make lint        # shellcheck shelltutor (FF-005; skips quietly if absent)
 make smoke       # FF-006a minimal static smoke test
-make verify      # check + lint + smoke (full gate)
+make verify      # released manifest check/tests + check + lint + smoke
+make manifest-check # declaration only; not a substitute for make verify
 make self-test   # exercise the checkers against built-in fixtures
 make lesson-flow # FF-006b PTY harness (optional; Python 3.9+; not in verify)
 ```
@@ -71,7 +72,15 @@ without being flagged.
 ## Contributor Tooling Floor
 
 The runtime tutor (`shelltutor`) is bash-only and POSIX-userland only,
-per AGENTS.md §Authority Levels. Optional contributor-side tooling
+per AGENTS.md §Authority Levels. Required contributor declaration verification
+uses Python 3.11+ (stdlib only) and Git 2.56+; select an already prepared Python
+with `make verify PYTHON=/absolute/path/to/python3` and put the prepared Git
+first on command-scoped `PATH`. No global tool pin, mise trust, environment
+activation or package installation is performed by the gate. The hosted setup
+uses Python 3.13.16 and checksum-pinned Git 2.56.0; see
+[the preparation and verdict contract](docs/project-manifest.md).
+
+Optional contributor-side tooling
 under `scripts/sim/` (FF-006b PTY harness) requires Python 3.9+ —
 syntax and stdlib use must not exceed that floor so the harness runs
 without a venv whenever Python 3.9+ is installed on macOS or Linux.
@@ -110,7 +119,9 @@ machine.
 
 ## GitHub Posture
 
-Following the Jefahnierocks workspace posture, this repository intentionally
-omits CI workflows, `CODEOWNERS`, PR templates, branch protection, and
-Actions secrets until a real activation trigger exists. Until then, local
-commit discipline is the enforcement layer.
+Owner-directed Specification 1 adoption is the activation trigger for the
+`verify` workflow. It runs on push and pull request without path or branch
+filters, job conditions or allowed failures. Its source preparation is separate
+from actual hosted qualification and branch-protection readback; record those
+results in `STATUS.md` before claiming enforcement. No deployment or secrets
+are needed. `CODEOWNERS`, PR templates and unrelated automation remain deferred.

Makefile

@@ -2,9 +2,8 @@
 #
 # Bash-only / POSIX-userland operations per AGENTS.md "Authority Levels".
 # Optional contributor-side tools (shellcheck) are invoked only when
-# present. CI activation is deferred per CONTRIBUTING.md "GitHub Posture";
-# these targets give contributors a one-command pre-commit verification
-# without imposing a CI dependency.
+# present. Contributor manifest verification uses prepared Python 3.11+ and
+# Git 2.56+; the learner-facing tutor still needs only Bash/POSIX tools.
 #
 # Targets:
 #   check        FF-001 + FF-002 + FF-004 + FF-007 static analysis (default)
@@ -14,9 +13,10 @@
 #   self-test    run checker self-tests against built-in fixtures
 #   help         list targets
 
-.PHONY: help check check-safety check-governance check-portability lint smoke lesson-flow verify self-test
+.PHONY: help check check-safety check-governance check-portability lint smoke lesson-flow verify self-test manifest-check manifest-self-test
 
 SCRIPT := shelltutor
+PYTHON ?= python3
 
 # Optional pass-through args for `lesson-flow`, e.g.:
 #   make lesson-flow SIMARGS='--variant current-rc -v'
@@ -28,7 +28,8 @@ help:
 	@printf '  lint         shellcheck $(SCRIPT) (FF-005)\n'
 	@printf '  smoke        FF-006a minimal static smoke test\n'
 	@printf '  lesson-flow  FF-006b PTY harness (optional; Python 3.9+; not in verify)\n'
-	@printf '  verify       check + lint + smoke\n'
+	@printf '  verify       manifest check/tests + check + lint + smoke\n'
+	@printf '  manifest-check      released declaration checks (prepared Python/Git)\n'
 	@printf '  self-test    run checker self-tests\n'
 
 check: check-safety check-governance check-portability
@@ -75,7 +76,13 @@ lesson-flow:
 	    printf 'lesson-flow: python3 not found; skipping (FF-006b; see docs/simulation-design-plan.md)\n'; \
 	fi
 
-verify: check lint smoke
+manifest-check:
+	@"$(PYTHON)" -I -S -B scripts/check-project-manifest.py
+
+manifest-self-test:
+	@"$(PYTHON)" -I -S -B -m unittest discover -s tests -p 'test_project_manifest.py' -v
+
+verify: manifest-check manifest-self-test check lint smoke
 
 self-test:
 	@./scripts/check-safety.sh --self-test

README.md

@@ -3,8 +3,8 @@ title: shelltutor
 category: reference
 component: project-overview
 status: active
-version: 0.1.0
-last_updated: 2026-07-14
+version: 0.2.0
+last_updated: 2026-10-17
 tags: [shell, bash, tutor, education, unix, posix]
 priority: high
 ---
@@ -53,7 +53,7 @@ shelltutor/
 ├── CONTRIBUTING.md   # Change discipline + Quality Gates
 ├── STATUS.md         # Current truth, posture, deferrals
 ├── ROADMAP.md        # Phase sequence; Phase 3 carries the curriculum spec
-├── project.yaml      # Meta-inventory project-intelligence manifest
+├── project.yaml      # Specification 1 project/workstation declaration
 ├── shelltutor        # The tutor itself (single bash script, executable)
 ├── Makefile          # Local quality gates and optional lesson-flow target
 ├── scripts/          # Static checkers, smoke test, and optional PTY harness
@@ -83,6 +83,12 @@ The tutor is a single bash script with no installation step:
 ./shelltutor -h       # help
 ```
 
+Contributors use `make verify` after preparing Python 3.11+ and Git 2.56+.
+These are validation tools, not learner prerequisites. See
+[project declaration and verification](docs/project-manifest.md) for offline
+release binding, linked-worktree arguments and CI setup. The tutor remains a
+single Bash script with no installation step.
+
 Requirements:
 
 - A POSIX-ish terminal on the target Linux or macOS surface; cross-platform

STATUS.md

@@ -3,8 +3,8 @@ title: shelltutor Status
 category: status
 component: project-status
 status: active
-version: 0.1.0
-last_updated: 2026-07-14
+version: 0.2.0
+last_updated: 2026-10-17
 tags: [status, posture, deferrals]
 priority: high
 ---
@@ -34,9 +34,16 @@ Current truth for the `shelltutor` repository.
 - Day-1 documentation set (`README.md`, `CLAUDE.md`, `AGENTS.md`,
   `CONTRIBUTING.md`, `STATUS.md`, `ROADMAP.md`) plus `docs/contracts.md`
   is in place.
-- Root `project.yaml` v0.1 projects this file into meta-inventory as a
-  public-available, linkable working prototype. It deliberately carries no
-  deployed-system or operational-state claim.
+- Root `project.yaml` follows Specification 1 and projects this file as a
+  public-available, linkable working prototype. Required operational state is
+  `unverified`; it makes no deployed-system claim. The development check points
+  to `scripts/verify-project.sh`, which delegates to the existing `make verify`.
+- Owner-directed adoption source is prepared with the public immutable Release 1
+  bundle and separate bootstrap. Contributor Python/Git prerequisites are separate
+  from the Bash/POSIX learner runtime. On 2026-10-17, all 23 focused regression
+  tests and the no-argument native gate passed locally with prepared Python 3.13.16
+  and Git 2.56.0. Hosted qualification, adoption acceptance and effective branch
+  enforcement remain pending; local source validation is not runtime acceptance.
 - The tutor script (`shelltutor`) was imported from prior-art at
   `fedora-top:~/Projects/shelltutor` (commit `136f6a3`, 2026-05-17).
 - **ROADMAP Phase 1 — User-Agnostic Refactor — is complete** (commit
@@ -122,7 +129,8 @@ Current truth for the `shelltutor` repository.
 |------------------|--------|--------------------|
 | `LICENSE` file | Not yet chosen; repo is public but default copyright applies | Before inviting outside reuse/contribution or tagging a release |
 | `CHANGELOG.md` | Nothing released yet; no tagged history | First tagged release |
-| GitHub-side automation (workflows, `CODEOWNERS`, PR templates, branch protection) | Workspace posture defers these until a real trigger exists | Real activation trigger |
+| `CODEOWNERS`, PR templates and unrelated GitHub automation | Not needed by the declaration migration | A project-specific need |
+| Hosted `verify` qualification and branch enforcement | Specification 1 adoption supplies the activation trigger; source is prepared | Actual hosted checks and effective protection readback |
 | Cross-platform CI | Same as above; manual validation suffices for now | When manual validation stops scaling |
 | Package distribution (Homebrew tap, AUR, etc.) | Single-file script; install is `clone + run` | If users ask for managed install |
 

docs/project-manifest.md

@@ -0,0 +1,94 @@
+---
+title: Project declaration and contributor verification
+category: reference
+component: project-interface
+status: active
+version: 0.1.0
+last_updated: 2026-10-17
+tags: [manifest, contributors, verification]
+priority: medium
+---
+
+# Project declaration and contributor verification
+
+`project.yaml` follows Specification 1 from
+[project-manifest Release 1](https://github.com/jefahnierocks/project-manifest/releases/tag/release-1).
+It is the one project declaration for inventory and workstation consumers.
+`STATUS.md` remains the detailed status of record. Declaration values neither
+execute commands nor prove a deployment, producer admission or runtime acceptance.
+
+The repo owns the offline binding in `scripts/check-project-manifest.py`:
+
+| Binding | Exact value |
+| --- | --- |
+| Release source | `56e3920089726e585eaa0fd7f4dc94e6938a1e0c` |
+| Domain-separated release-table digest | `f7ff9dd0972af5d3a6a3348c3e092de1a6acd97fa3975e13e522cf80ce5e7df2` |
+| Separate bootstrap SHA-256 | `2ccf58e0da97bbbd9dae173d1cca047d465c4a2d950ee6e56052309a9689cf4f` |
+
+The twenty-file payload plus descriptor live in `vendor/project-manifest/release-1/`.
+The separately pinned bootstrap is `vendor/project-manifest/release_verifier.py`.
+These are unmodified public MIT artifacts, with the license retained. That license
+does not decide shelltutor's still-deferred product license. Git attributes protect
+their literal bytes and the root manifest's LF representation. Re-vendoring is a
+reviewed project change, not an automatic dependency update.
+
+## Contributor entrypoint
+
+Prepare Python 3.11+ and Git 2.56+ outside the gate, then run `make verify` or
+`scripts/verify-project.sh`. The latter takes no arguments and delegates to Make.
+The gate uses no network and installs nothing. A selected interpreter can be passed
+as `PYTHON=/absolute/path/to/python3`; put prepared Git first on a command-scoped
+`PATH`. Never change global runtimes to satisfy this repo.
+
+`make verify` checks the independently bound release, the declaration and consumer
+regressions, then preserves the existing static, optional ShellCheck and smoke
+checks. `make self-test` still exercises the four native checkers. Python/Git are
+contributor tools only: a learner still runs `./shelltutor` with Bash/POSIX tools.
+The optional PTY harness retains its separate Python 3.9+ floor and its existing
+non-gating status. The five-stage human portability walks remain separate.
+
+The declaration maps only `check` to the executable wrapper. Setup/build/dev/test/
+format roles are null rather than inventing commands; native checker self-tests
+remain available through Make. Activation is `none`, with no secrets, stacks or
+host requirements. Empty platforms makes no architecture qualification claim.
+
+## Observation selection
+
+No arguments selects tracked working bytes. A newly added target must be in the
+index before Git can include it in this observation. Direct staged checking uses:
+
+```bash
+python3 -I -S -B scripts/check-project-manifest.py --staged
+```
+
+For a linked worktree, explicitly provide its reviewed Git common directory with
+`--git-common-dir /absolute/common/directory`, or set `SHELLTUTOR_GIT_COMMON_DIR`
+for `make verify`. No other checkout is inferred or searched. Inherited Git
+overrides are refused; the gate never silently removes them.
+
+`--rev FULL_COMMIT_OID`, or `SHELLTUTOR_MANIFEST_REV` for Make/CI, checks the
+declaration and references in that commit's tree. Native checks still execute the
+current checkout; a revision selector does not certify a historical native gate.
+Each observation uses one captured UTC date. Exit 0 means the released declaration
+checks and this repo's expected command/activation shape passed; exit 1 means an
+invalid declaration, binding mismatch or shape disagreement; exit 2 means a check
+could not run. The JSON keeps declaration, native-shape and runtime claims separate.
+
+## Hosted preparation
+
+The new `verify` workflow is a source proposal until its first actual hosted run
+passes. It uses Ubuntu 24.04, explicitly selected Python 3.13.16 from setup-python,
+and the Git-only `scripts/prepare-ci-git.py`. Preparation downloads Git 2.56.0 from
+the fixed kernel.org URL, checks its pinned official HTTPS SHA-256, and builds into
+one fresh runner-owned temporary prefix with no Rust or install hardlinks. It does
+not install a Python floor, Gitleaks or project dependencies. Compiler/zlib build
+prerequisites are prepared explicitly in the ephemeral runner. This is not a tar
+signature verification claim.
+
+Only the verification step prepends that Git to PATH. `make verify` receives the
+explicit prepared Python and full GitHub commit OID. Both push and pull_request
+run without branch/path filters; the job is named `verify`. Workflow existence does
+not prove effective required checks. Actual hosted qualification and protection
+readback are recorded separately before landing/enforcement claims.
+See [the current qualification status](../STATUS.md) for completed and pending
+checks.