Ls Localsetup Framework Changes

---
name: ls-localsetup-framework-changes
description: "Pre-task workflow, certainty assessment, context load, document status, testing, Git checkpoints, document maintenance. Use for framework modifications, PRDs, or any task that must follow checklist and checkpoints."
metadata:
  version: "1.2"
---

# Framework Compliance

Use this skill when a task affects LocalSetup framework behavior, shipped skills, installer/runtime rules, repo documentation, PRDs, or any workflow where rule compliance and traceability matter.

## Pre-Task Flow

Before changing files:

1. Identify the task type: documentation, skill, framework code, installer, tests, git operation, PRD/queue work, or release workflow.
2. Load the active repo context from the repository instructions and the relevant documents under `ls/docs/`.
3. Run or request the context check when framework state is uncertain:

```bash
./ls/tools/verify_context
```

4. Check core constraints before acting: repo/data separation, user-owned worktree edits, secret/private state exclusion, platform compatibility, and required tests.
5. Assess certainty. If the active docs do not answer a core-rule question, pause for clarification before making a risky change.

## Current Sources Of Truth

Use active active sources only:

- Owning skills and workflow packages for operational behavior. Public docs carry `owner_skill` or `owner_package` frontmatter so agents know what to load.
- `ls/docs/AGENTIC_DESIGN_INDEX.md` for agent-facing design and workflow doc navigation.
- `ls/docs/WORKFLOW_REGISTRY.md` for named workflows and their triggers.
- `ls/docs/DOCUMENT_LIFECYCLE_MANAGEMENT.md` for document status meanings and ownership metadata.
- `ls/docs/SKILLS_AND_RULES.md` and `ls/docs/AGENT_SKILLS_COMPLIANCE.md` as public references for skill format and loading rules; `ls-create-agent-skills` and `ls-task-skill-matcher` own execution behavior.
- `ls/docs/REPO_AND_DATA_SEPARATION.md` as the public reference for framework source versus repo-local data boundaries; this skill owns the operational guardrail.
- `ls/docs/QUICKSTART.md` for supported verification commands.
- `ls/config/platforms.yaml` and `ls/docs/PLATFORM_REGISTRY.md` for supported platform paths.
- `ls/config/pack.yaml` for pack membership and `extensions.skill_taxonomy`; generated catalogs must not invent their own classification.

Do not reference removed removed draft helper files or indexes. In particular, do not call missing rule-enforcer or document-maintenance shell helpers, and do not rely on non-existent YAML document/rule indexes.

## Document Status Check

Before relying on a framework document:

1. Open the actual Markdown file under `ls/docs/`.
2. Read its YAML frontmatter.
3. Treat `status: ACTIVE` as current guidance.
4. Treat `status: PROPOSAL`, `DRAFT`, `DEPRECATED`, or `ARCHIVED` as non-authoritative unless the user explicitly asks you to work from it.
5. For active public framework docs, read `owner_skill` or `owner_package` and load that owner for operational rules before changing behavior.
6. If `status:` or ownership is missing, treat the document as uncertain and cross-check against an active index or ask before relying on it for core behavior.
7. When adding or materially changing a framework doc, include `status:`, `version:`, and the appropriate owner field.

The status meanings are defined in [DOCUMENT_LIFECYCLE_MANAGEMENT.md](../../docs/DOCUMENT_LIFECYCLE_MANAGEMENT.md).

## Implementation Guardrails

- Preserve unrelated work. If the worktree is dirty, identify your owned files and do not revert edits made by others.
- Keep framework source in `ls/`; do not put generated private state, local secrets, or machine-specific agent data into tracked files.
- For skill changes, keep `SKILL.md` Agent Skills compatible with `name` and `description` frontmatter, and keep auxiliary files scoped to the skill directory.
- Prefer the repo's active Python and shell tooling over ad hoc helpers.
- Use relative links for repo docs and verify they still resolve.
- For PRD or workflow queue work, update status/outcome fields only in the relevant active queue or PRD files.
- Apply the [friction-free founding principle](../../docs/WORKFLOW_STANDARD.md#founding-design-principle) during normal work and review: improve existing owners, automate routine reversible work within authority, and reuse unchanged approvals and applicable evidence. Add a gate only for a named safety, correctness, or acceptance need; do not add duplicate checks, reviewers, ledgers, polling loops, mandatory phases, or a separate friction audit. Preserve security, signatures, privacy, and user control.

## Verification

Choose checks based on the surface changed:

```bash
./ls/tools/verify_context
./ls/tools/verify_rules
uv run --locked python ls/tools/localsetup.py --source-root . validate-catalog
uv run --locked python ls/tools/localsetup.py --source-root . scan-migration
uv run --locked python ls/tools/localsetup.py --source-root . audit-global-first
uv run --locked ./ls/tests/automated_test.sh
workers="$(uv run --locked python ls/tools/localsetup.py --source-root . test-workers)"
uv run --locked pytest -n "$workers" ls/tests -q
git diff --check
```

- Run `verify_context` when validating that the framework context is present.
- Run `verify_rules` after framework or rule-related changes.
- Run `validate-catalog` after skill, catalog, platform, or registry changes.
- Run `validate-package-surface` after package materialization, deployed docs, resolver-token, workflow, or path-contract changes.
- Run `scan-migration` when migration, installer, adapter, generated-artifact, or source-boundary behavior may be affected.
- Run `audit-global-first` when global-first layout, lockfile, target-state, PowerShell removal, or source/target docs claims may be affected.
- Run focused tests and compliance checks for the code you changed before broad suites. Use the full pytest suite only as final consolidation for broad/shared runtime behavior, release/publish work, dependency changes, or explicit user requests. Resolve the permitted worker count with `localsetup test-workers`; [COMMAND_REFERENCE.md](../../docs/COMMAND_REFERENCE.md) owns its formula and aggregate-budget rule.

The default local aggregate test-worker budget is `max(1, floor(available logical CPU cores / 3))`. A configured positive integer override may increase or decrease that budget, with a hard cap of the available logical CPU count. Resolve and enforce the budget in code from the selected repository configuration; agents and users edit settings, not scheduling calculations. Hosted shard jobs each use their isolated runner's CPU and memory budget; matrix concurrency bounds active jobs. Concurrent test processes on one host share that host's budget; they must not each claim it. Preserve stricter native execution limits.

For a serial illustrative pytest run, use `uv run --locked pytest -n 1 ls/tests -q`; use `localsetup test-workers` to query an appropriately bounded parallel run.

## Git And Handoff

- Shared, global, client, and repository authorization plus no-write boundaries govern execution. A workflow checkpoint does not grant commit authority.
- Create commits only when authorized by the active user instruction or standing authorization.
- Use Conventional Commit style for normal commits.

- Never stage broad unrelated work from a dirty worktree.
- In the final handoff, report changed files, checks run and results, and any residual risk or skipped checks.

## Proportional validation and evidence reuse

Run inexpensive checks and focused tests while editing. One successful full
suite for the final candidate is sufficient; authoritative CI may provide it.
Do not run another local suite or repeat a successful suite for the same tested
inputs just because a task moves from PR to main or publication. Record the
commit, environment, command/workflow, and result; invalidate evidence only when
relevant inputs change. Bound long jobs, preserve successful jobs when retrying
an understood failure, and stop automatic retries on an unexplained failure.
Complete source changes and the release record before generating final docs.

LocalSetup's hosted implementation derives its shard matrix and concurrency
from the repository's testing configuration, with each shard using the available CPUs of its isolated runner
and an all-shards success gate and exact-commit Actions evidence. The publishing workflow
checks that evidence before building instead of running the full suite again.
See [repository maintenance](../../docs/REPO_MAINTENANCE.md#validation-reuse).