create-agentic-workspace 0.6.0 → 0.8.0

package/README.md

@@ -17,8 +17,11 @@ never pre-grants anything — it *declares*, the platform's trust dialog is the
 ## What it does
 
 - Emits the plugin's reviewed three-tier permission map verbatim into the new workspace's
-  committed `.claude/settings.json`, alongside `extraKnownMarketplaces` and `enabledPlugins`
-  pinned to an exact marketplace ref (`autoUpdate: false` — no floating grant).
+  committed `.claude/settings.json`, alongside `extraKnownMarketplaces` and `enabledPlugins`.
+  As of `feat-foundry-installer-unpinning`, the marketplace registration names no ref at all
+  (`autoUpdate: false` still stops it from floating on its own — no floating grant); the ARTIFACT
+  fetched is what stays pinned, via the untouched `plugins[].source.sha` in the marketplace
+  manifest, which `sha` outranks `ref` at install time regardless of which index ref is named.
 - Absorbs `foundry-bootstrap.sh`'s out-of-session `git` commit-identity isolation (`--gh-account`),
   proved differentially equal to the shipped script.
 - Scaffolds a seven-file, schema-valid workspace seed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The pre-session bootstrap wizard for an Agentic Foundry workspace: declares (never grants) the permission floor, absorbs foundry-bootstrap.sh's out-of-session identity wiring, and scaffolds a seven-file schema-valid workspace. Zero dependencies, no lifecycle scripts, no telemetry.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.6.0",
+    "plugin_version": "1.8.0",
     "pins_researched": "2026-08-02"
   }
 }

package/permission-floor.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "plugin_root_glob": "~/.claude/plugins/cache/*/foundry/*",
-  "generated_for_plugin_version": "1.6.0",
+  "generated_for_plugin_version": "1.8.0",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",
@@ -356,6 +356,10 @@
       "script": "foundry_id_apply.py",
       "rationale": "pure decision library: no argparse/main()/__main__; exposes classify_gitops/decide_apply as pure functions (R5)"
     },
+    {
+      "script": "foundry_main_catalogue.py",
+      "rationale": "the shipped __main__ runs only as a push-scoped CI workflow step (.github/workflows/ci.yml); never instructed by any skill or hook in an agent session"
+    },
     {
       "script": "foundry_permission_floor.py",
       "rationale": "pure library: no argparse/main()/__main__; imported by scripts/foundry-doctor.py's permission-floor probe (feat-foundry-doctor-permission-floor-check), never in command position"

package/src/floorReconcile.mjs

@@ -65,14 +65,60 @@ export function classifyPin(settingsObj, pins) {
   const entry = ((settingsObj && settingsObj.extraKnownMarketplaces) || {})[pins.marketplace_name];
   if (entry === undefined) return { state: 'absent', ref: null, skew: false };
   const ref = entry && entry.source && entry.source.ref;
-  const pinned = typeof ref === 'string' && ref !== '' && !ref.includes('*') && entry.autoUpdate === false;
+  // feat-foundry-installer-unpinning (AC-IUP-5). Both installers now register the marketplace
+  // TAGLESS by default (AC-IUP-1/AC-IUP-3), so "no ref" must classify as pinned, not unpinned — an
+  // ABSENT ref is well-formed (refAbsent), distinct from a malformed EXPLICIT one (empty string, or
+  // carrying a wildcard, both still refused below). AC-IUP-4's Clarifications also widen the
+  // autoUpdate check from `=== false` to `!== true`: the shell installer has no --autoUpdate flag
+  // on `claude plugin marketplace add` and a verified isolated run wrote no such key at all, so an
+  // ABSENT autoUpdate must read the same as an explicit `false` — never merely tolerate `true`.
+  //
+  // SECURITY REVIEW (PR #132): widening "no ref" to `pinned` must NOT also widen it to "any entry".
+  // Property access on a primitive yields undefined rather than throwing, so `{}`, `"x"` and `[]`
+  // all reach refAbsent -- and NOTHING here compared the entry's own repo to ours, so a tagless
+  // entry naming a FOREIGN repository under our key would classify pinned and be granted the 42
+  // wildcarded cache allow rules, with the report REASSURING the operator about a manifest that is
+  // not ours. Before this atom that input hit the brake and warned. An entry must therefore be a
+  // plain object naming OUR github source before "no ref" can mean anything. `autoUpdate` is
+  // accepted only as absent-or-false: `!== true` admitted truthy coercions (1, "true") that the
+  // platform may honour as auto-update-on, which is wider than AC-IUP-5's text.
+  const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+  const src = isPlainObject(entry) && isPlainObject(entry.source) ? entry.source : null;
+  // Both operands undefined must NOT compare equal: a pin block that lost marketplace_repo
+  // would otherwise make every source carrying no repo key classify as ours.
+  const ourRepo = typeof pins.marketplace_repo === 'string' && pins.marketplace_repo !== ''
+    ? pins.marketplace_repo : null;
+  // GitHub owner/repo is CASE-INSENSITIVE, so `LukasRepublic/agentic-foundry` is the SAME
+  // repository. Comparing byte-exact would classify it unpinned and tell the operator "not ours",
+  // which is false. Normalize both sides; the comparison stays exact-match otherwise.
+  // Gate on the ASCII shape GitHub can actually issue BEFORE folding. toLowerCase() is
+  // locale-independent but NOT injective: U+212A KELVIN SIGN folds to ASCII 'k', and this repo's
+  // name contains one -- so "lu\u212Aasrepublic/agentic-foundry" would fold equal and read as
+  // ours. No such string can name a real GitHub repository, so it buys a false reassurance rather
+  // than attacker-controlled code; the shape gate closes the class outright, including whatever
+  // confusable the next Unicode revision adds.
+  const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+  const sameRepo = typeof src?.repo === 'string' && REPO_RE.test(src.repo) && !!ourRepo
+    && src.repo.toLowerCase() === ourRepo.toLowerCase();
+  const isOurSource = !!src && sameRepo && src.source === 'github';
+  const refAbsent = isOurSource && ref === undefined;
+  const refWellFormed = isOurSource
+    && (refAbsent || (typeof ref === 'string' && ref !== '' && !ref.includes('*')));
+  const autoUpdateOk = entry && (entry.autoUpdate === undefined || entry.autoUpdate === false);
+  const pinned = refWellFormed && autoUpdateOk;
   // A pin can be perfectly well-formed and still name a DIFFERENT plugin than the map these rules
   // came from. The 42 allow rules are wildcarded across the cache and their per-script rationales
   // were reviewed against THIS version's scripts; writing them over a workspace pinned at an older
   // one grants the same paths against different code. Surfaced rather than refused — the operator's
-  // review of the plan is the control, and it can only work if the skew is on screen.
-  const skew = pinned && ref !== `v${pins.plugin_version}`;
-  return { state: pinned ? 'pinned' : 'unpinned', ref: typeof ref === 'string' ? ref : null, skew };
+  // review of the plan is the control, and it can only work if the skew is on screen. AC-IUP-8: a
+  // tagless (refAbsent) entry has nothing to compare against a version, so it can never be "skewed"
+  // — computing `ref !== vX` against a null ref would otherwise fire the warning on every run.
+  const skew = pinned && !refAbsent && ref !== `v${pins.plugin_version}`;
+  // The foreign/malformed-source case must not render as an ordinary ref-shaped 'unpinned':
+  // its remediation ("pin the marketplace") can NEVER clear it, because refWellFormed requires
+  // isOurSource. Carry the reason so renderPlan can say the thing the operator can act on.
+  const reason = pinned ? null : (!isOurSource ? 'source' : (!autoUpdateOk ? 'autoUpdate' : 'ref'));
+  return { state: pinned ? 'pinned' : 'unpinned', ref: typeof ref === 'string' ? ref : null, skew, reason };
 }
 
 /** Compute the delta WITHOUT touching the filesystem. Returns
@@ -215,15 +261,26 @@ export function renderPlan(plan, { applied }) {
     lines.push(`  + marketplace pin added — the bundled allow rules are wildcarded across the plugin cache and are bounded only by it`);
   } else if (plan.pin.state === 'pinned') {
     // printed on EVERY pinned run, not only the skewed one: an operator cannot notice a mismatch
-    // that is never shown, and this is the branch where 42 grants are written without comment
+    // that is never shown, and this is the branch where 42 grants are written without comment.
+    // AC-IUP-8: a TAGLESS entry (plan.pin.ref === null, the default registration as of
+    // feat-foundry-installer-unpinning) must never render as "pinned at null" — say what actually
+    // bounds it instead. classifyPin's `skew` is already forced false for this case, so the
+    // trailing VERSION SKEW clause never appends here.
+    const refDisplay = plan.pin.ref === null
+      ? 'the default catalogue (tagless index; the artifact commit stays fixed by the manifest\'s source.sha)'
+      : plan.pin.ref;
     lines.push(
-      `  · marketplace pinned at ${plan.pin.ref}; these rules come from the floor generated for v${plan.pinsVersion}` +
+      `  · marketplace pinned at ${refDisplay}; these rules come from the floor generated for v${plan.pinsVersion}` +
         (plan.pin.skew ? ' — VERSION SKEW: the same wildcarded paths will resolve to that pin\'s scripts, not this one\'s' : ''),
     );
   } else if (plan.withheldAllow) {
     lines.push(
-      `  ! marketplace entry present but unpinned (ref=${plan.pin.ref === null ? 'none' : plan.pin.ref})` +
-        ' — allow-tier rules WITHHELD; ask and deny still applied. Pin the marketplace, then re-run.',
+      plan.pin.reason === 'source' || plan.pin.reason === 'autoUpdate'
+        ? `  ! the marketplace entry ${plan.pin.reason === 'autoUpdate' ? 'sets autoUpdate to something other than false' : "does not name this marketplace's github source"}` +
+          ' — allow-tier rules WITHHELD; ask and deny still applied. Pinning will NOT clear this:' +
+          ' the registered source itself is not ours. Inspect the entry before re-running.'
+        : `  ! marketplace entry present but unpinned (ref=${plan.pin.ref === null ? 'none' : plan.pin.ref})` +
+          ' — allow-tier rules WITHHELD; ask and deny still applied. Pin the marketplace, then re-run.',
     );
   }
   for (const rule of plan.blanket) {

package/src/permissionFloor.mjs

@@ -214,17 +214,52 @@ export function buildSettings(map, pins) {
   for (const e of map.entries) {
     byTier[e.tier].push(e.rule);
   }
-  // THE PINNED LITERAL (AC-BCL-4(b), contract v1.2 — PR #61 security review Block 1). `ref` is
-  // load-bearing, not decoration: without it the adopter's FIRST marketplace resolution floats to
-  // whatever the default branch points at, and because the floor's allow rules are
-  // version-wildcarded (`cache/*/foundry/*/scripts/...`), the operator's single trust acceptance
-  // becomes a standing grant over whatever code that resolution delivered. That is the same
-  // floating-pin defect `autoUpdate: false` guards the LATER fetches against, left open on the
-  // first one — and strictly weaker than the manual path docs/QUICKSTART.md documents
-  // (the documented `marketplace add …#<tag>` install line). Single-sourced from
-  // the `foundry` pin block, so it cannot drift from the marketplace manifest.
+  // THE PINNED LITERAL — SUPERSEDED (feat-foundry-installer-unpinning, AC-IUP-3). This block used
+  // to read (AC-BCL-4(b), contract v1.2 — PR #61 security review Block 1), verbatim:
+  //
+  //   "THE PINNED LITERAL (AC-BCL-4(b), contract v1.2 — PR #61 security review Block 1). `ref` is
+  //   load-bearing, not decoration: without it the adopter's FIRST marketplace resolution floats
+  //   to whatever the default branch points at, and because the floor's allow rules are
+  //   version-wildcarded (`cache/*/foundry/*/scripts/...`), the operator's single trust acceptance
+  //   becomes a standing grant over whatever code that resolution delivered. That is the same
+  //   floating-pin defect `autoUpdate: false` guards the LATER fetches against, left open on the
+  //   first one — and strictly weaker than the manual path docs/QUICKSTART.md documents (the
+  //   documented `marketplace add …#<tag>` install line). Single-sourced from the `foundry` pin
+  //   block, so it cannot drift from the marketplace manifest."
+  //
+  // That reasoning was CORRECT at the time and is not dismissed — it is superseded, on grounds
+  // re-derived from the LIVE repository configuration (not a shipped adopter template, which an
+  // earlier draft of the supersession wrongly cited and then withdrew), recorded in full in
+  // specs/features/foundry/onboarding/installer-unpinning/feat-foundry-installer-unpinning.md
+  // ("This SUPERSEDES a prior security-review Block"). Summary of the three grounds:
+  //   (i)   Ref integrity does not distinguish "pinned" from "tagless" on THIS repository: `main`
+  //         is Tier A (6 required status contexts, enforce_admins, strict) and `refs/tags/v*` is
+  //         doubly ruleset-protected (immutable, one ruleset with bypass_actors: []). The Block's
+  //         threat model — an index that "floats to whatever the default branch points at" — is
+  //         not a tampering threat here; both refs are equally tamper-resistant.
+  //   (ii)  The index pin controls CADENCE, not integrity, and that cost is paid three other ways:
+  //         AC-IUP-4 makes BOTH installers register with an explicit-or-effective `autoUpdate:
+  //         false` (this one keeps writing the literal `false`; the shell installer's Clarified
+  //         resolution is that an ABSENT key reads identically, per floorReconcile.mjs's `pinned`
+  //         predicate below); the untouched, content-addressed `plugins[].source.sha` in
+  //         `.claude-plugin/marketplace.json` fixes exactly what commit is fetched regardless of
+  //         which ref the index names; and `.github/workflows/btb-gates-base.yml`'s
+  //         `^\.claude-plugin/` security-path rule gates what may enter the catalogue at all.
+  //   (iii) The Block's own mechanism never implemented the Block's stated threat: this same
+  //         floorReconcile.mjs already classified `ref: "main"` (a branch) as PINNED before this
+  //         atom, and `scripts/foundry-bootstrap.sh --channel edge` already shipped exactly that
+  //         floating-ref state as a supported, if opt-in, option. And the withholding branch this
+  //         Block relied on (`floorReconcile.mjs`'s `withheldAllow`) only runs on the RECONCILE
+  //         path against an ALREADY-EXISTING entry — never on this create path, which the Block's
+  //         own "the adopter's FIRST marketplace resolution" language describes.
+  // AC-IUP-5 is a NECESSARY CONSEQUENCE of removing `ref` here, not a mitigation invented to excuse
+  // it: without floorReconcile.mjs's predicate change below, EVERY adopter's reconcile run would
+  // silently drop the allow tier. The residual this supersession leaves OPEN, not closed: nothing
+  // in this atom bounds what may land on `main` beyond the security-path label — the sibling
+  // default-branch catalogue gate (not delivered here) is what closes that gap. Single-sourced
+  // from the `foundry` pin block, so `repo` cannot drift from the marketplace manifest.
   const marketplaceEntry = {
-    source: { source: 'github', repo: pins.marketplace_repo, ref: `v${pins.plugin_version}` },
+    source: { source: 'github', repo: pins.marketplace_repo },
     autoUpdate: false,
   };
   return {