/hq-access — the access ladder

When someone cannot find or open a file under companies/<slug>/…, do not reply "the file does not exist". Exactly one of three things is true, and this skill tells you which and fixes what it can:

1. never-existed — the path is not in the vault (offer to create it if a generator exists).
2. not-synced — it is in the vault and you can read it, but it is not on this machine. Fetch and pin it.
3. no-access — it is in the vault but you lack a grant. Ask the right owner once, with a ready-made grant command.

User input: $ARGUMENTS — a path (companies/<slug>/knowledge/report.md or knowledge/report.md) or free text naming the file ("the August platinum report"). Optional flags pass straight through: --company <slug>, --no-fix, --yes.

Step 1 — Parse the target

• If $ARGUMENTS looks like a path (contains / or a file extension), use it verbatim.
• Otherwise treat it as a search query. Never guess a key from free text: the CLI (or the backup ladder) will search and, on several hits, you MUST ask the user to pick with AskUserQuestion before touching anything.
• Resolve the company: --company, else the companies/<slug>/ anchor in the path, else the active company in <hqRoot>/.hq/config.json.

Step 2 — Run the CLI ladder (preferred)

hq access "<target>" --json [--company <slug>] [--no-fix]

hq access ships in @indigoai-us/hq-cli >= 5.109.0. It vends through /sts/vend, checks the exact prefix ACL (carve-out denies honoured, "no ACL record" = membership-distributed, not denied), fetches and pins on not-synced (running hq sync status / hq sync doctor and retrying once if the fetch fails), and on no-access resolves the grantor and asks once before sending the DM.

Read the JSON: { outcome, path, company, exists, steps[], grantor?, localPath?, requestSentAt?, alreadyAskedAt?, candidates? }. Exit codes: 0 local or not-synced, 2 never-existed, 3 no-access or pending-confirmation, 4 ambiguous.

• ambiguous (exit 4): show candidates with AskUserQuestion (one question, the keys as options), then re-run with the chosen path.
• pending-confirmation (exit 3): the CLI resolved the grantor but did not send because --json was used without --yes. Go to Step 4.
• Any other outcome: report it in the words of Step 5.

If the command fails with unknown command 'access' / error: unknown command, or hq --version is below 5.109.0, fall back to Step 3.

Step 3 — Backup ladder (older CLIs)

Run the same rungs in the same order with the commands every CLI already has. Stop at the first rung that decides the outcome.

1. Resolve. Exact path first. Otherwise hq files search "<query>" --company <slug>; one hit proceeds, several hits go to AskUserQuestion (never auto-pick), zero hits → never-existed.
2. Exists? hq files browse companies/<slug>/<dir>/ --company <slug> and look for the key. Absent → never-existed.
3. Access? hq files acl <company-relative-prefix> --company <slug>. "No ACL record exists" on a company file is normal — treat as accessible. Your effective permission: missing, none, or deny (including a carve-out deny on the exact prefix under a broader read) → no-access.
4. Not local? ls <hqRoot>/companies/<slug>/<key>. Present → local. Otherwise hq files get companies/<slug>/<key> --company <slug> (materializes and pins). If get fails for a non-403 reason: hq sync status, then hq sync doctor --reconcile-conflicts (dry-run; add --yes only if it reports conflict twins), then retry get exactly once. If the output contains a bulk-asymmetry circuit-breaker message, surface it verbatim and stop — never override it.
5. No access → ask the owner. Grantor = the Creator: from hq files acl if there is a row (map the uid to a person with hq members list --company <slug>), else the company owner, then admins from the same list. Bare names go through hq people resolve <name> --company <slug>. Then Step 4.

Step 4 — The one confirmation before the owner DM

Always show the resolved recipient email first, then ask exactly one question (use AskUserQuestion when available, plain y/N otherwise):

Ask <name> <email> for read access to <company-relative-prefix>?

Only on yes:

hq dm <grantor-email> "<requester-email> is asking for read access to <prefix> in <slug>." \
  --prompt "hq files share <prefix> --with <requester-email> --permission read --company <slug>"

or, when the CLI has hq access, re-run it with --yes. Never send without that answer, never send twice for the same (requester, prefix, grantor) within 24 hours (<hqRoot>/.hq/access-requests.json is the ledger; say "already asked " instead), and never print share-session URLs or secrets.

Step 5 — Report in plain language

End with exactly one of:

• never created — "<path> was never created in the vault." Offer to create it if a generator exists.
• not synced, now fixed — "Fetched and pinned; now local at <absolute path>." Then open it.
• no access, owner asked — "The file exists but you do not have read access. Asked ; you will get a DM when granted."

Never reply "the file does not exist" without naming which of the three it is (policy hq-failed-file-open-runs-access-ladder).

See also

• /hq-files — grants, ACLs, browse/cat/get, pins
• /hq-sync — full sync, hq sync status, hq sync doctor
• /hq-heal --class access — routes here
• /dm — the notification primitive the request rung uses