diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 8c1fb6b..4e5e4ae 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -9,13 +9,13 @@ ## Key Files | File | Description | |------|-------------| -| None | GitHub metadata is organized in subdirectories. | +| `pull_request_template.md` | Default PR body, including exact snapshot provenance labels parsed by the guard. | +| `scripts/check_snapshot_provenance.py` | Base/head blob comparison plus PR decision validation. | ## Subdirectories | Directory | Purpose | |-----------|---------| -| `ISSUE_TEMPLATE/` | Structured issue form YAML files (see `ISSUE_TEMPLATE/AGENTS.md`). | -| `PULL_REQUEST_TEMPLATE/` | Pull request description template (see `PULL_REQUEST_TEMPLATE/AGENTS.md`). | +| `ISSUE_TEMPLATE/` | Numbered `.yml` issue forms and chooser config (see `ISSUE_TEMPLATE/AGENTS.md`). | | `scripts/` | Repository governance scripts, including snapshot provenance validation. | | `workflows/` | GitHub Actions workflow definitions (see `workflows/AGENTS.md`). | @@ -28,11 +28,11 @@ ### Testing Requirements - Validate YAML syntax for workflow or issue template edits. - For workflow changes, mirror commands locally where practical before relying on CI. -- Run `pytest tests/test_governance.py` when provenance scripts, workflow wiring, or PR declarations change. +- Run `pytest tests/test_governance.py tests/test_release_workflow.py` when provenance scripts, workflow wiring, or PR declarations change. ### Common Patterns -- CI installs the package with development dependencies and runs lint/type/test checks. -- Snapshot runtime changes require one validated provenance decision from the PR body. +- `test.yml` is both normal CI and the local reusable workflow called by a tag release. +- Snapshot runtime PRs require one validated provenance decision; non-PR runs still enforce append-only provenance content. ## Dependencies diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/01-bug-report.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/bug_report.yaml rename to .github/ISSUE_TEMPLATE/01-bug-report.yml diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/02-feature-request.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/feature_request.yaml rename to .github/ISSUE_TEMPLATE/02-feature-request.yml diff --git a/.github/ISSUE_TEMPLATE/documentation.yaml b/.github/ISSUE_TEMPLATE/03-documentation.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/documentation.yaml rename to .github/ISSUE_TEMPLATE/03-documentation.yml diff --git a/.github/ISSUE_TEMPLATE/question.yaml b/.github/ISSUE_TEMPLATE/04-question.yml similarity index 100% rename from .github/ISSUE_TEMPLATE/question.yaml rename to .github/ISSUE_TEMPLATE/04-question.yml diff --git a/.github/ISSUE_TEMPLATE/AGENTS.md b/.github/ISSUE_TEMPLATE/AGENTS.md index e785ab3..604ab3b 100644 --- a/.github/ISSUE_TEMPLATE/AGENTS.md +++ b/.github/ISSUE_TEMPLATE/AGENTS.md @@ -1,5 +1,5 @@ - + # ISSUE_TEMPLATE @@ -9,11 +9,11 @@ ## Key Files | File | Description | |------|-------------| -| `bug_report.yaml` | Form for reproducible defects and environment details. | -| `config.yaml` | GitHub issue template chooser configuration. | -| `documentation.yaml` | Form for documentation improvements or corrections. | -| `feature_request.yaml` | Form for proposed enhancements. | -| `question.yaml` | Form for usage questions. | +| `01-bug-report.yml` | Form for reproducible defects and environment details. | +| `02-feature-request.yml` | Form for proposed enhancements. | +| `03-documentation.yml` | Form for documentation improvements or corrections. | +| `04-question.yml` | Form for usage questions. | +| `config.yml` | GitHub issue chooser configuration and valid contact links. | ## Subdirectories | Directory | Purpose | @@ -25,9 +25,10 @@ ### Working In This Directory - Keep issue forms scoped to this Python CLI/MCP project. - Preserve valid GitHub issue form YAML structure. +- Ordering is controlled by numbered filenames; `config.yml` has no `issue_templates` key. ### Testing Requirements -- Validate YAML syntax after edits. +- Validate YAML syntax and run `pytest tests/test_governance.py` after path/schema edits. ### Common Patterns - Forms collect structured fields rather than relying on free-form Markdown only. diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yml similarity index 65% rename from .github/ISSUE_TEMPLATE/config.yaml rename to .github/ISSUE_TEMPLATE/config.yml index 22c70cf..0514fab 100644 --- a/.github/ISSUE_TEMPLATE/config.yaml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -7,20 +7,10 @@ contact_links: - name: 📖 项目文档 url: https://github.com/codeasier/pt-snap-cli/tree/main/docs about: 查看项目文档和使用指南 - - name: 💬 讨论区 - url: https://github.com/codeasier/pt-snap-cli/discussions - about: 在讨论区提问或分享想法 - name: 📧 联系我们 url: mailto:825770651@qq.com about: 通过邮件联系我们 -# 模板排序(按此顺序显示在 Issue 选择页面) -issue_templates: - - bug_report.yaml - - feature_request.yaml - - documentation.yaml - - question.yaml - # ============================================================ # 标签与模板映射 # ============================================================ @@ -28,10 +18,10 @@ issue_templates: # # | 模板文件 | 自动标签 | 说明 | # |--------------------|-------------------|----------------| -# | bug_report.yaml | bug | 错误报告 | -# | feature_request.yaml | enhancement | 功能请求 | -# | documentation.yaml | documentation | 文档问题 | -# | question.yaml | question | 问题咨询 | +# | 01-bug-report.yml | bug | 错误报告 | +# | 02-feature-request.yml | enhancement | 功能请求 | +# | 03-documentation.yml | documentation | 文档问题 | +# | 04-question.yml | question | 问题咨询 | # # 如需添加更多标签,编辑对应模板文件的 `labels:` 字段 # 示例:labels: ["bug", "critical", "help-wanted"] diff --git a/.github/PULL_REQUEST_TEMPLATE/AGENTS.md b/.github/PULL_REQUEST_TEMPLATE/AGENTS.md deleted file mode 100644 index ae11934..0000000 --- a/.github/PULL_REQUEST_TEMPLATE/AGENTS.md +++ /dev/null @@ -1,42 +0,0 @@ - - - -# PULL_REQUEST_TEMPLATE - -## Purpose -`PULL_REQUEST_TEMPLATE` contains the default pull request description template used for repository contributions. - -## Key Files -| File | Description | -|------|-------------| -| `pull_request_template.md` | PR body template for summaries, testing, and review context. | - -## Subdirectories -| Directory | Purpose | -|-----------|---------| -| None | PR template content is flat. | - -## For AI Agents - -### Working In This Directory -- Keep checklist items aligned with current verification expectations. -- Avoid adding process requirements that CI or project documentation does not support. -- Preserve the exact snapshot provenance decision/reason labels parsed by `.github/scripts/check_snapshot_provenance.py`. - -### Testing Requirements -- Review Markdown rendering after edits. -- Run `pytest tests/test_governance.py` when changing provenance declarations. - -### Common Patterns -- The template should prompt contributors for what changed and how it was tested. -- Snapshot runtime changes require exactly one `updated` or `no-update` decision; `no-update` also requires a specific reason. - -## Dependencies - -### Internal -- `.github/workflows/` defines automated checks referenced by PR guidance. - -### External -- GitHub pull request template Markdown support. - - diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/pull_request_template.md similarity index 100% rename from .github/PULL_REQUEST_TEMPLATE/pull_request_template.md rename to .github/pull_request_template.md diff --git a/.github/scripts/check_snapshot_provenance.py b/.github/scripts/check_snapshot_provenance.py index 110eae7..27fbe3a 100644 --- a/.github/scripts/check_snapshot_provenance.py +++ b/.github/scripts/check_snapshot_provenance.py @@ -6,7 +6,6 @@ import subprocess import sys from collections.abc import Sequence -from pathlib import Path SNAPSHOT_PREFIX = "src/pt_snap_cli/snapshot/" PROVENANCE_PATH = f"{SNAPSHOT_PREFIX}PROVENANCE.md" @@ -44,6 +43,38 @@ def changed_paths(base: str, head: str) -> list[str]: return [os.fsdecode(path) for path in result.stdout.split(b"\0") if path] +def git_blob(ref: str, path: str) -> bytes | None: + result = subprocess.run( + ["git", "show", f"{ref}:{path}"], + check=False, + capture_output=True, + ) + return result.stdout if result.returncode == 0 else None + + +def validate_append_only(base: bytes | None, head: bytes | None) -> list[bytes]: + """Return inserted lines while rejecting changes to existing provenance lines.""" + if head is None: + raise GuardError(f"Append-only provenance file was deleted: {PROVENANCE_PATH}.") + + base_lines = [] if base is None else base.splitlines(keepends=True) + head_lines = head.splitlines(keepends=True) + base_index = 0 + inserted: list[bytes] = [] + for line in head_lines: + if base_index < len(base_lines) and line == base_lines[base_index]: + base_index += 1 + else: + inserted.append(line) + + if base_index != len(base_lines): + raise GuardError( + f"{PROVENANCE_PATH} is append-only; existing lines may not be deleted, " + "rewritten, truncated, or reordered." + ) + return inserted + + def _declarations(body: str) -> dict[str, list[str]]: declarations = {DECISION_LABEL.lower(): [], REASON_LABEL.lower(): []} for match in _DECLARATION.finditer(body): @@ -53,7 +84,11 @@ def _declarations(body: str) -> dict[str, list[str]]: return declarations -def validate_provenance(changes: Sequence[str], body: str) -> str: +def validate_provenance( + changes: Sequence[str], + body: str, + inserted_lines: Sequence[bytes] = (), +) -> str: snapshot_changes = [path for path in changes if path.startswith(SNAPSHOT_PREFIX)] if not snapshot_changes: return "No snapshot runtime changes detected." @@ -75,10 +110,12 @@ def validate_provenance(changes: Sequence[str], body: str) -> str: if decision == "updated": if PROVENANCE_PATH not in changes: raise GuardError(f"The 'updated' decision requires a change to {PROVENANCE_PATH}.") - if not Path(PROVENANCE_PATH).is_file(): - raise GuardError(f"The updated provenance declaration is missing: {PROVENANCE_PATH}.") + if not any(line.strip() for line in inserted_lines): + raise GuardError(f"The 'updated' decision requires new content in {PROVENANCE_PATH}.") return f"Snapshot provenance updated in {PROVENANCE_PATH}." + if PROVENANCE_PATH in changes: + raise GuardError(f"The 'no-update' decision cannot include a change to {PROVENANCE_PATH}.") if len(reasons) != 1: raise GuardError(f"The 'no-update' decision requires one '{REASON_LABEL}:' declaration.") reason = reasons[0] @@ -96,10 +133,31 @@ def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--base", required=True, help="Base commit SHA") parser.add_argument("--head", required=True, help="Head commit SHA") + parser.add_argument( + "--require-decision", + action="store_true", + help="Require the PR provenance declaration in PR_BODY", + ) args = parser.parse_args() try: - message = validate_provenance(changed_paths(args.base, args.head), os.getenv("PR_BODY", "")) + changes = changed_paths(args.base, args.head) + inserted_lines: Sequence[bytes] = () + if PROVENANCE_PATH in changes: + inserted_lines = validate_append_only( + git_blob(args.base, PROVENANCE_PATH), + git_blob(args.head, PROVENANCE_PATH), + ) + if args.require_decision: + message = validate_provenance( + changes, + os.getenv("PR_BODY", ""), + inserted_lines, + ) + elif PROVENANCE_PATH in changes: + message = f"Append-only snapshot provenance validated in {PROVENANCE_PATH}." + else: + message = "No snapshot provenance content changes detected." except (GuardError, subprocess.CalledProcessError) as exc: print(f"Snapshot provenance guard failed: {exc}", file=sys.stderr) return 1 diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md index 32f4cc6..c4d38d7 100644 --- a/.github/workflows/AGENTS.md +++ b/.github/workflows/AGENTS.md @@ -9,8 +9,8 @@ ## Key Files | File | Description | |------|-------------| -| `test.yml` | PR provenance gate plus lint, type, test-matrix, coverage, build, and wheel smoke checks. | -| `release.yml` | Release workflow for building and publishing package artifacts. | +| `test.yml` | Reusable provenance, lint, type, test-matrix, coverage, build, and wheel smoke checks. | +| `release.yml` | Tag workflow that gates build and publication on the tagged commit's reusable quality workflow. | ## Subdirectories | Directory | Purpose | @@ -24,6 +24,7 @@ - Treat release workflow edits as high-impact and verify syntax carefully. - Do not bypass tests, lint, type checks, or publishing safeguards without explicit instruction. - Keep snapshot provenance inputs and declaration parsing aligned with `.github/scripts/check_snapshot_provenance.py` and the PR template. +- Keep release validation before PyPI publication; release notes and package version must be validated in `build`. ### Testing Requirements - Validate YAML syntax. @@ -33,6 +34,7 @@ ### Common Patterns - Workflows install the package with development extras before verification. - The test workflow defines independent provenance, lint, and Python-version test jobs that may run concurrently. +- Release ordering is `quality` -> `build` -> `publish` -> `github-release`; the local reusable workflow is resolved from the tag commit. ## Dependencies diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fb07364..c8d8feb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,8 +8,13 @@ permissions: contents: read jobs: + quality: + name: Verify tagged commit + uses: ./.github/workflows/test.yml + build: name: Build distribution + needs: quality runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -39,6 +44,25 @@ jobs: - name: Verify package runs run: pt-snap --version + - name: Extract release notes from changelog + run: | + python - <<'PY' + import os + import re + from pathlib import Path + + tag = os.environ["GITHUB_REF"].removeprefix("refs/tags/v") + text = Path("CHANGELOG.md").read_text() + pattern = rf"^## \[{re.escape(tag)}\].*?$(.*?)(?=^## \[|\Z)" + match = re.search(pattern, text, re.MULTILINE | re.DOTALL) + if not match: + raise SystemExit(f"CHANGELOG.md does not contain release notes for ## [{tag}]") + notes = match.group(1).strip() + if not notes: + raise SystemExit(f"CHANGELOG.md release notes for ## [{tag}] are empty") + Path("release-notes.md").write_text(notes + "\n") + PY + - name: Upload build artifacts uses: actions/upload-artifact@v4 with: @@ -46,6 +70,13 @@ jobs: path: dist/ retention-days: 90 + - name: Upload release notes + uses: actions/upload-artifact@v4 + with: + name: release-notes + path: release-notes.md + retention-days: 90 + publish: name: Publish to PyPI needs: build @@ -88,25 +119,10 @@ jobs: name: dist path: dist/ - - name: Extract release notes from changelog - run: | - TAG=${GITHUB_REF#refs/tags/v} - python - <<'PY' - import os - import re - from pathlib import Path - - tag = os.environ["GITHUB_REF"].removeprefix("refs/tags/v") - text = Path("CHANGELOG.md").read_text() - pattern = rf"^## \[{re.escape(tag)}\].*?$(.*?)(?=^## \[|\Z)" - match = re.search(pattern, text, re.MULTILINE | re.DOTALL) - if not match: - raise SystemExit(f"CHANGELOG.md does not contain release notes for ## [{tag}]") - notes = match.group(1).strip() - if not notes: - raise SystemExit(f"CHANGELOG.md release notes for ## [{tag}] are empty") - Path("release-notes.md").write_text(notes + "\n") - PY + - name: Download release notes + uses: actions/download-artifact@v4 + with: + name: release-notes - name: Create GitHub Release run: | diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d3b47e1..ed9d044 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,6 +1,7 @@ name: Test on: + workflow_call: push: branches: [main] pull_request: @@ -17,7 +18,6 @@ concurrency: jobs: snapshot-provenance: name: Snapshot provenance - if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -25,11 +25,31 @@ jobs: fetch-depth: 0 - name: Require provenance evaluation for snapshot runtime changes + if: github.event_name == 'pull_request' env: BASE_SHA: ${{ github.event.pull_request.base.sha }} HEAD_SHA: ${{ github.event.pull_request.head.sha }} PR_BODY: ${{ github.event.pull_request.body }} - run: python .github/scripts/check_snapshot_provenance.py --base "$BASE_SHA" --head "$HEAD_SHA" + run: >- + python .github/scripts/check_snapshot_provenance.py + --base "$BASE_SHA" --head "$HEAD_SHA" --require-decision + + - name: Enforce append-only provenance outside pull requests + if: github.event_name != 'pull_request' + env: + BEFORE_SHA: ${{ github.event.before }} + HEAD_SHA: ${{ github.sha }} + REF_TYPE: ${{ github.ref_type }} + run: | + if [ "$REF_TYPE" = "tag" ]; then + BASE_SHA=$(git describe --tags --abbrev=0 "${HEAD_SHA}^" 2>/dev/null || git rev-list --max-parents=0 "$HEAD_SHA") + else + BASE_SHA="$BEFORE_SHA" + if ! git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then + BASE_SHA=$(git rev-list --max-parents=0 "$HEAD_SHA") + fi + fi + python .github/scripts/check_snapshot_provenance.py --base "$BASE_SHA" --head "$HEAD_SHA" lint: name: Lint & Format @@ -42,7 +62,7 @@ jobs: python-version: "3.13" - name: Install dependencies - run: pip install -e .[dev] + run: pip install -e ".[dev]" - name: Ruff lint check run: ruff check . @@ -75,10 +95,10 @@ jobs: pip-${{ runner.os }}-${{ matrix.python-version }}- - name: Install dependencies - run: pip install -e .[dev] + run: pip install -e ".[dev]" - name: Run tests with coverage - run: pytest --cov --cov-report=xml --cov-report=term-missing + run: pytest tests/test_fixture_provenance.py && pytest --cov --cov-report=xml --cov-report=term-missing - name: Upload coverage report uses: actions/upload-artifact@v4 diff --git a/AGENTS.md b/AGENTS.md index 972e389..5e9f6ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ and an MCP server over shared service-layer behavior. Run these commands from the repository root. - Install for local development: `pip install -e .` -- Install development dependencies: `pip install -e .[dev]` +- Install development dependencies: `pip install -e ".[dev]"` - Run all tests: `pytest` - Run one file: `pytest tests/test_cli.py` - Run one test: `pytest tests/test_cli.py -k test_version_flag` @@ -33,7 +33,9 @@ that local environment is intentionally available. | GitHub automation | [.github/AGENTS.md](.github/AGENTS.md) | Issue/PR templates, provenance guard, CI, and release workflows | | User documentation | [docs/AGENTS.md](docs/AGENTS.md) | English/Chinese guides, API docs, navigation, and legal evidence | | Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules | -| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and trusted fixtures | +| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures | +| Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs | +| Setup skill | [skills/AGENTS.md](skills/AGENTS.md) | Installation skill approval and active-interpreter safety boundary | ## Runtime Topology @@ -88,14 +90,15 @@ templates under category subdirectories are included by - Pickle input is trusted-code execution, not a sandbox. Never load an untrusted fixture or snapshot merely to inspect it. - Import writes and validates metadata on a temporary database before - `os.replace()` publishes it. Preserve the existing destination on failure. + publication. When focus update is requested, publication retains a rollback + link until the atomic focus write succeeds; reported failure preserves the + previous destination. - Split requires exactly one positive strategy (`--slices` or `--max-entries`), an absent destination, replay-validates generated slices, and publishes the staged directory without replacement. -- `src/pt_snap_cli/snapshot/PROVENANCE.md` is append-only. Changes below the - snapshot runtime require the provenance decision enforced by - `.github/scripts/check_snapshot_provenance.py` and covered by - `tests/test_governance.py`. +- `src/pt_snap_cli/snapshot/PROVENANCE.md` is append-only. The guard compares + base/head Git blobs on PRs, main pushes, and releases; snapshot-runtime PRs + additionally require the exact provenance decision in the default PR template. ## Change Routing @@ -103,12 +106,14 @@ templates under category subdirectories are included by | --- | --- | --- | | CLI options or terminal rendering | `src/pt_snap_cli/cli.py` and the owning core service | `tests/test_cli.py`, `tests/test_completion.py` | | Focus precedence or persistence | `src/pt_snap_cli/config.py`, `src/pt_snap_cli/core/focus_service.py`, `src/pt_snap_cli/context.py` | `tests/test_config.py`, `tests/test_context.py`, `tests/core/test_focus_service.py` | +| Context/executor caching | `src/pt_snap_cli/core/context_cache.py`, `src/pt_snap_cli/api.py`, `src/pt_snap_cli/core/query_service.py` | `tests/core/test_context_cache.py`, `tests/test_snapshot_analyzer_cache.py`, `tests/test_query_cache_perf.py` | | Query schema, SQL, or categories | `src/pt_snap_cli/query/`, `src/pt_snap_cli/core/query_service.py` | `tests/query/`, `tests/core/test_query_service.py` | | MCP or Python API behavior | `src/pt_snap_cli/api.py`, `src/pt_snap_cli/mcp/server.py` | `tests/test_api.py`, `tests/test_mcp_server.py`, `tests/test_contract_cli_mcp.py` | | Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` | | Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` | | Reports | `src/pt_snap_cli/core/report_service.py`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` | | Packaging or release | `pyproject.toml`, `.github/workflows/` | `tests/test_package.py`, `tests/test_release_workflow.py` | +| Executable fixtures | `tests/fixtures/snapshots/` | `tests/test_fixture_provenance.py` before any deserializing suite | ## Documentation Boundaries diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md new file mode 100644 index 0000000..b87f273 --- /dev/null +++ b/benchmarks/AGENTS.md @@ -0,0 +1,26 @@ + + +# benchmarks + +## Purpose +`benchmarks` contains opt-in performance measurements. These scripts are not +pytest entry points: they can consume substantial CPU, memory, and time, and the +import benchmark deserializes reviewed executable fixtures. + +## Entry Points +| File | Behavior | +| --- | --- | +| `baseline_import.py` | Runs warmup/formal imports in temporary directories, profiles one import, and prints timing, RSS, database, and correctness summaries. | +| `sqlite_write_throughput.py` | Compares default and optimized SQLite writers using temporary databases. | + +## Safety And Execution +- Run from the repository root with `PYTHONPATH=src python benchmarks/