troubleshoot

# Troubleshoot macstack-dev ## Lint failures | Symptom | Cause → fix | |---|---| | `entity master problem` | master does not appear in stores exactly once with role=master → add a store with the master role or fix the `master` field | | `category not in registry` | typo or a new niche → check `references/software-categories.json`; a new category = a kebab-case slug + a registry proposal (PR), never a silent custom value | | `rating mismatch` | agentic.rating disagrees with the channels → rule: 3×true=full, 2=good, 1=basic, only "partial"=partial | | `trigger unknown` | a workflow references a trigger code missing from `triggers[]` → triggers live ONLY in the collection, never inline | | `delegation not downward` | an orchestrator appears in a worker's delegates_to → the hierarchy is strictly control_plane → orchestrator → worker | | `cross-stack not declared` | the `foo:` prefix is not declared → add the stack to `stacks.root/substacks/links` | | `lint red on rule 12.24` | a table exceeds the format budget (>4 columns, a cell >80 chars, <3 rows, or `<br>`/bold/code/pipes in a cell) → convert it to a list, see `documents/references/format-rules.md` | | `lint red on rule 12.25` | prose is not in `docs.language` → translate the prose; identifiers (ids, YAML keys, anchors, statuses, file paths) always stay English, see `documents/references/format-rules.md` | ## Prototype resolution - `github:owner/repo` fails to clone → check `gh auth status` / repo visibility; private repos need a PAT. Fallback: ask the user for a local absolute path. - The repo has no `macstack.json` → it is a legacy prototype (only `stack.json`): use its files for scaffolding, but there is nothing to inherit — open a `client/OPEN-QUESTIONS.md §B` row and point at it by id from `lifecycle.open_questions` (prose in the markdown, pointer in the JSON). - A prototype cycle (A→B→A) → an error by design; break the chain. - A local path inside a cloud-synced folder (iCloud/Drive) may hang on first read (file materialization) — retry, or copy the prototype to a regular folder. ## Infisical / env - `infisical secrets` reads the wrong instance or organization → the profile in use is not the project's. `infisical profile current` says which profile applies and why (a stale `INFISICAL_PROFILE` pin or `--profile` beats a bound directory, which beats the default). Fix: keep each instance as its own profile — `infisical login --save-as <profile> --domain=<domain>` once, then `infisical profile bind <profile>` in the project root (or `--profile <profile>`). - A command fails because the domain differs from the login → a `--domain` / `INFISICAL_DOMAIN` names another instance than the profile in use; this is the CLI refusing to read the wrong vault, not a bug. Select the profile that belongs to that instance, or unset the override. - `unknown command "profile"` / `unknown flag: --profile` → the CLI is older than 0.43.134; upgrade it. - `.env` got wiped empty → setup.sh lacks the guard: fetch into a temp file, mv only on success. Restore by pulling from Infisical again. - A required key exists in macstack.json but is empty after sync → it is missing in Infisical: create it there; `provided_by: client` → move to `lifecycle.needs_from_client`. - Values with `$`/spaces break `source .env` → render `KEY='value'` in single quotes (embedded quote → `'\''`). ## Scaffold - A user file got overwritten → an idempotency violation: an existing file with differences = diff + question, never a silent overwrite. Restore from git. - Generated files contradict the architecture → the source order was violated: prototype → stack plugins → dev plugins; redo starting from the prototype. - `${VAR}` from .mcp.json does not resolve → values must live in the env block of `.claude/settings.local.json` (filled by scripts/setup.sh), not inside .mcp.json. ## The `macstack/` folder | Symptom | Cause → fix | |---|---| | Two `macstack.json` (root and folder) | lint errors on both → keep the folder copy, `git rm` the root one via `/macstack-dev:start` (migration mode) | | Lint red on a document that reads fine | anchors were stripped (client returned an edited copy, or someone pasted through a WYSIWYG) → re-insert anchors idempotently; never rewrite the document | | A cross-reference check reports a missing ID that is visibly present | a Cyrillic homoglyph in the ID token — Latin and Cyrillic A B E K M H O P C T Y X are indistinguishable on screen. Do not try to spot it; find it with `grep -RPn "[^\x00-\x7F]-[0-9]" macstack/`, which matches a non-ASCII letter directly before the hyphen-number of an ID, then retype the token in ASCII | | A client PDF reads as empty | not-yet-materialized iCloud file → size/first-bytes check before reading; refuse rather than guess | | `.xlsx` cannot be opened by any file tool | ask for a CSV export beside it and write NO log entry, so the file stays in the unprocessed set | | `D<n>` cited but nowhere to be found | the rulings file was written without allocating in `history/DECISIONS.md` first | | A script prints in the wrong language | it never wired in `documents/references/i18n.py` → report it via `/macstack-dev:feedback` | ## Discovery - `curl raw.githubusercontent.com/...marketplace.json` → 404: the branch is not `main` or the repo is private → use `gh api repos/agents-store/claude-plugins/contents/...`. - No plugin exists for a software → open a §B row (pointer from `lifecycle.open_questions`, never prose in the JSON) + suggest creating it via plugin-creator; do NOT put a non-existent name into context.plugins.