@mmerterden/multi-agent-pipeline 20.8.1 → 20.8.2

package/pipeline/scripts/unattended_policy.py

@@ -451,7 +451,14 @@ def structural_refusal(cmd):
     return None
 
 
+# shlex is quadratic in a token's length; a longer segment is split on
+# whitespace with quotes and backslashes removed (agent-guard.py coarse_tokens).
+SHLEX_MAX_CHARS = 16384
+
+
 def tokenize(text):
+    if len(text) > SHLEX_MAX_CHARS:
+        return [re.sub(r"[\"'\\]", "", t) for t in text.split()]
     try:
         return shlex.split(text)
     except ValueError:
@@ -2603,9 +2610,11 @@ TOOLKIT_PREFIX = "mcp__multi-agent-toolkit__"
 # Keys a toolkit tool uses for a filesystem destination it writes. Checked with
 # check_path so a toolkit call cannot write a screenshot, recording, build
 # output or export over a protected path. MCP tools run outside the OS sandbox,
-# so this is their only path boundary.
-TOOLKIT_PATH_KEYS = ("path", "filename", "out_dir", "output_path", "output_dir",
-                     "export_path", "derived_data_path", "result_bundle_path",
+# so this is their only path boundary. The toolkit's write parameters are
+# listed in test/fixtures/toolkit-path-params.json, generated from its tool
+# schemas, and the unattended-guard test checks each one against this list.
+TOOLKIT_PATH_KEYS = ("path", "filename", "out_dir", "output", "output_path", "output_dir",
+                     "output_graph", "export_path", "derived_data_path", "result_bundle_path",
                      "figma_path", "screenshot_path", "video_path", "file_path")
 
 

package/pipeline/scripts/uninstall.mjs

@@ -49,6 +49,7 @@ import {
   writeFileSync,
 } from "fs";
 import { execFileSync } from "child_process";
+import { createHash } from "crypto";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
@@ -82,6 +83,22 @@ export const PIPELINE_AGENT_FILES = [
  */
 export const PIPELINE_CORE_SKILL_DIRS = ["apple-archive-compliance", "google-play-compliance"];
 
+/**
+ * Files the installer ships into ~/.claude/templates (install/templates/).
+ * Used only for an install that predates the install manifest; a unit test
+ * asserts it matches the source tree.
+ */
+export const PIPELINE_TEMPLATE_FILES = [
+  "claude-hooks.json",
+  "codex-instructions.md",
+  "copilot-instructions.md",
+  "multi-agent-autopilot-awake.plist.template",
+  "multi-agent-autopilot.plist.template",
+];
+
+/** Written by install/_common.mjs writeInstallManifest at the host dir root. */
+export const INSTALL_MANIFEST = ".pipeline-manifest.json";
+
 const flags = process.argv.slice(2).filter((a) => a !== "uninstall");
 
 const TOOL_FLAGS = [
@@ -238,6 +255,65 @@ function preservePrefsCredentialMapping(prefsPath) {
   );
 }
 
+function sha256Of(path) {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function rmdirIfEmpty(dir) {
+  try {
+    if (readdirSync(dir).length > 0) return;
+  } catch {
+    return;
+  }
+  rmIfExists(dir);
+}
+
+/**
+ * Remove the co-owned files the install manifest records (top-level commands,
+ * lib/, templates/), each only while its hash is still the one installed. An
+ * edited file is the user's now and stays. Returns false when there is no
+ * manifest, so the caller falls back to the pre-manifest cleanup.
+ *
+ * @param {string} hostDir e.g. ~/.claude
+ * @param {string[]} keepInLib lib/ files kept on purpose
+ * @returns {boolean}
+ */
+function rmManifestFiles(hostDir, keepInLib) {
+  const manifestPath = join(hostDir, INSTALL_MANIFEST);
+  let files;
+  try {
+    files = JSON.parse(readFileSync(manifestPath, "utf-8"))?.files;
+  } catch {
+    return false;
+  }
+  if (!files || typeof files !== "object") return false;
+  const kept = [];
+  const dirs = new Set();
+  for (const [rel, hash] of Object.entries(files)) {
+    if (typeof rel !== "string" || rel.split("/").some((part) => part === ".." || part === "")) {
+      continue;
+    }
+    if (rel.startsWith("lib/") && keepInLib.includes(rel.slice(4))) continue;
+    const path = join(hostDir, rel);
+    if (!existsSync(path)) continue;
+    dirs.add(dirname(path));
+    if (sha256Of(path) === hash) rmIfExists(path);
+    else kept.push(rel);
+  }
+  for (const dir of [...dirs].sort((a, b) => b.length - a.length)) {
+    if (dir !== join(hostDir, "commands")) rmdirIfEmpty(dir);
+  }
+  if (kept.length > 0) {
+    console.log(`    kept ${kept.length} file(s) you changed since install: ${kept.join(", ")}`);
+  }
+  rmIfExists(manifestPath);
+  return true;
+}
+
 /**
  * Conditional rm  -  respects --dry-run.
  * @param {string} path
@@ -766,8 +842,19 @@ export async function main() {
     rmIfExists(join(CLAUDE, "scripts"));
     // Pipeline-managed trees the installer lays down alongside scripts/.
     rmIfExists(join(CLAUDE, "multi-agent-refs"));
+    rmIfExists(join(CLAUDE, ".pipeline-swap"));
     rmIfExists(join(CLAUDE, "schemas"));
-    rmDirExcept(join(CLAUDE, "lib"), KEEP_IN_LIB);
+    if (!rmManifestFiles(CLAUDE, KEEP_IN_LIB)) {
+      // An install that predates the manifest wiped lib/ and templates/ on
+      // every run, so their shipped names are the pipeline's. The top-level
+      // commands cannot be told from the user's own and stay.
+      rmDirExcept(join(CLAUDE, "lib"), KEEP_IN_LIB);
+      rmMatchingFiles(join(CLAUDE, "templates"), (name) => PIPELINE_TEMPLATE_FILES.includes(name));
+      rmdirIfEmpty(join(CLAUDE, "templates"));
+      console.log(
+        `    note: no ${INSTALL_MANIFEST}; top-level files in ${join(CLAUDE, "commands")} were left in place`,
+      );
+    }
     rmIfExists(join(CLAUDE, ".pipeline-version"));
     // NOTE: ~/.claude/rules/ is USER-OWNED. install lays baseline rules down
     // write-if-missing and NEVER overwrites them (install/claude.mjs

package/pipeline/scripts/usage-identity.mjs

@@ -200,7 +200,7 @@ function persist(prefsPath, patch, env) {
         j.global.usageLog = { ...(j.global.usageLog || {}), ...patch };
         return j;
       },
-      { mode: 0o600, timeoutMs: lockTimeoutFrom(env) },
+      { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(env) },
     );
     return written !== undefined;
   } catch {

package/pipeline/scripts/usage-register.mjs

@@ -230,7 +230,7 @@ export function persistPrefs(
         if (registeredAs) j.global.usageLog.registeredAs = registeredAs;
         return j;
       },
-      { mode: 0o600, timeoutMs: lockTimeoutFrom(process.env) },
+      { mode: 0o600, followSymlink: true, timeoutMs: lockTimeoutFrom(process.env) },
     );
     return written !== undefined;
   } catch {

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-26T20:19:12Z",
+  "generatedAt": "2026-09-27T07:55:06Z",
   "skillCount": 218,
   "entries": [
     {
@@ -357,7 +357,7 @@
     },
     {
       "path": "shared/external/callkit-voip/SKILL.md",
-      "sha256": "0a7102e006a54e38011e24c274c50b0988f210cdd34fb6405ba5db922f23d3e7"
+      "sha256": "44646c2f192170a5468c18a0c78fb77ffcf135bb8d8cf2a7581ac2d1c0909eeb"
     },
     {
       "path": "shared/external/ci-cd-pipelines/SKILL.md",
@@ -369,7 +369,7 @@
     },
     {
       "path": "shared/external/cloudkit-sync/SKILL.md",
-      "sha256": "842889bc86a8be353871c6f2104a8f5f8e506cd81203e135ee25911cac050526"
+      "sha256": "9464e93c0435628f3628a6f1775b7478dea75514b0fb3aa3cc09c7cec83be48d"
     },
     {
       "path": "shared/external/compose-components/SKILL.md",
@@ -405,7 +405,7 @@
     },
     {
       "path": "shared/external/core-nfc/SKILL.md",
-      "sha256": "0f58b94d639b887588a472385791762181286ab30f015b423d868a1cef8fa5d7"
+      "sha256": "c838b7e38bb0c65f409674220ef9f6b668839ce2c0546609b75c69c1d7c18567"
     },
     {
       "path": "shared/external/coreml/SKILL.md",
@@ -569,7 +569,7 @@
     },
     {
       "path": "shared/external/localization-reuse-map/SKILL.md",
-      "sha256": "ee6d437ed7ea18111074797532376d7bc09419eb3cfef6d8dde5679592457903"
+      "sha256": "0a7429a2bbc2454b12ae4fb9af1eb09cc5a5d1ab96c05c693fc4827747bd8d15"
     },
     {
       "path": "shared/external/macos-menubar-tuist-app/SKILL.md",
@@ -613,7 +613,7 @@
     },
     {
       "path": "shared/external/passkit-wallet/SKILL.md",
-      "sha256": "5780862b6f98b9a2b65975a79c690d2b200126f1004fac5055907b89f4bd8a0f"
+      "sha256": "972a26763ef557d6534e970c6a444526c0fc3eb0ac005f01ac1fee103e052e58"
     },
     {
       "path": "shared/external/pdfkit/SKILL.md",
@@ -621,11 +621,11 @@
     },
     {
       "path": "shared/external/pencilkit-drawing/SKILL.md",
-      "sha256": "080a07ed7fb2f2065030a9d0c543023035b11a180cdc069026be195464afb12e"
+      "sha256": "f18ccc4d5d985492758003aba555ccbfbede2e9c18c70932dc7c1198c4c2f624"
     },
     {
       "path": "shared/external/permissionkit/SKILL.md",
-      "sha256": "92167db142929bcfcb9458163d540bc4badc141dd5de5f7f98e7a5dc79b5b6db"
+      "sha256": "ea30c7a3bb9128a5f43064d5d2e46360d1fe08c732eb3ecedd63490d7d4420a5"
     },
     {
       "path": "shared/external/photos-camera-media/SKILL.md",
@@ -637,7 +637,7 @@
     },
     {
       "path": "shared/external/push-notifications/SKILL.md",
-      "sha256": "f962752d6e540cdd8e98e96f9b0790eccede1d0a88bf5bd22928891d26d172f3"
+      "sha256": "9f73964265e99c21aa0bab61b153a77ad3ac953f45766c852b1c8cfbef8498c3"
     },
     {
       "path": "shared/external/python-patterns/SKILL.md",
@@ -649,7 +649,7 @@
     },
     {
       "path": "shared/external/realitykit-ar/SKILL.md",
-      "sha256": "9c576081a515662c03d462fa0a15828f6e8ab02c8e14e1d4911fc0cfceef47fb"
+      "sha256": "66726df1164bb6ca96878cb941b4395ff3cff10ebc6743f91aa22b8ec795c246"
     },
     {
       "path": "shared/external/rest-api-design/SKILL.md",
@@ -829,7 +829,7 @@
     },
     {
       "path": "shared/external/vision-framework/SKILL.md",
-      "sha256": "68ef66fc020e65885f47e26e665c88365bbbf52cb1fb8fb8de5c4cab7237c9e8"
+      "sha256": "370fdf6eaf71833dff0e8f2d3989a849b5c42ff3198605aa818c2fd0c12c7ef7"
     },
     {
       "path": "shared/external/vue-composition/SKILL.md",

package/pipeline/skills/shared/external/callkit-voip/SKILL.md

@@ -70,9 +70,12 @@ delegate conformance below is `@preconcurrency`, so those callbacks run as
 main-actor code and the `Task` each one starts inherits that isolation. That is
 what lets a `Task` hold on to the non-`Sendable` `CXAction` and `CXProvider`
 it was handed; from a nonisolated method Swift 6 rejects the same capture with
-"passing closure as a 'sending' parameter risks causing data races". The name the
-system shows comes from `localizedName`; on current SDKs it is read from the
-bundle display name, and the old `init(localizedName:)` is deprecated.
+"passing closure as a 'sending' parameter risks causing data races". The
+system shows the app's bundle display name for the provider. The
+`localizedName` property ("No longer supported") and `init(localizedName:)`
+(replaced by `init()`) are both deprecated as of iOS 14 and Mac Catalyst 14,
+so create the configuration with `CXProviderConfiguration()` and do not set a
+name.
 
 ## Incoming call flow
 

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -307,6 +307,48 @@ func moveToCloud(_ local: URL) {
 Watch for changes with an `NSMetadataQuery` whose search scope is
 `NSMetadataQueryUbiquitousDocumentsScope` or `NSMetadataQueryUbiquitousDataScope`.
 
+### Coordinated reads and writes
+
+The iCloud daemon reads and writes files in the ubiquity container at the same
+time as the app, so every direct access to a ubiquitous file goes through
+`NSFileCoordinator`. Do the file work only inside the accessor block and only
+with the URL it passes in, which can differ from the one requested. A
+coordinated read of a ubiquitous item waits for its contents to download
+unless `.immediatelyAvailableMetadataOnly` is passed. Coordination blocks the
+calling thread, so keep it off the main actor.
+
+```swift
+nonisolated func readCoordinated(_ url: URL) throws -> Data {
+    var coordinationError: NSError?
+    var result: Result<Data, any Error> = .failure(CocoaError(.fileReadUnknown))
+    NSFileCoordinator().coordinate(readingItemAt: url, options: [], error: &coordinationError) { safeURL in
+        result = Result { try Data(contentsOf: safeURL) }
+    }
+    if let coordinationError { throw coordinationError }
+    return try result.get()
+}
+
+nonisolated func writeCoordinated(_ data: Data, to url: URL) throws {
+    var coordinationError: NSError?
+    var writeError: (any Error)?
+    NSFileCoordinator().coordinate(writingItemAt: url, options: .forReplacing, error: &coordinationError) { safeURL in
+        do { try data.write(to: safeURL, options: .atomic) } catch { writeError = error }
+    }
+    if let coordinationError { throw coordinationError }
+    if let writeError { throw writeError }
+}
+```
+
+An object that keeps a file open (an editor, a live preview) adopts
+`NSFilePresenter` so it hears about changes, moves and deletions that iCloud
+makes: implement `presentedItemURL`, return a private `OperationQueue` from
+`presentedItemOperationQueue` (the main queue invites deadlocks), react in
+`presentedItemDidChange()`, and pair `NSFileCoordinator.addFilePresenter(_:)`
+with `removeFilePresenter(_:)`. Create the presenter's own coordinators with
+`NSFileCoordinator(filePresenter:)` so it is not told about its own writes.
+`UIDocument` already does all of this, so a document-based app gets
+coordination by subclassing it.
+
 ## Account status
 
 Check the account before any sync, and listen for `.CKAccountChanged`.
@@ -393,6 +435,7 @@ func merged(_ error: CKError) -> CKRecord? {
 - [ ] `.userDeletedZone` handled
 - [ ] SwiftData review gives both the model-compatibility and schema-rollout verdicts
 - [ ] Key-value store external-change notification observed
+- [ ] Ubiquitous files read and written through `NSFileCoordinator`; open files have an `NSFilePresenter`
 - [ ] Encryption review mentions: references cannot be encrypted, encrypted fields cannot be queried or sorted, assets are encrypted already
 - [ ] `CKSyncEngine` state serialization saved (iOS 17+)
 

package/pipeline/skills/shared/external/core-nfc/SKILL.md

@@ -259,6 +259,37 @@ rejects the capture. Always connect before sending any command. The `select`, `i
 block reads, MIFARE and FeliCa calls), which is written out in the
 [patterns reference](references/nfc-patterns.md).
 
+### Session configuration (iOS 26.4)
+
+iOS 26.4 adds `NFCTagReaderSession.Configuration`, a value that carries the
+polling options plus optional subsets of the ISO 7816 select identifiers and
+FeliCa system codes from Info.plist (entries not listed there are dropped; an
+empty array means all of them). `init(configuration:delegate:queue:)` builds a
+session from it and, unlike `init?(pollingOption:delegate:queue:)`, is not
+failable; the older initializer is deprecated as of 26.4.
+`restartPolling(configuration:)` restarts discovery with a different
+configuration for that one restart only: a later plain `restartPolling()` goes
+back to the configuration the session was created with. The new initializer,
+like the old one, is unavailable to app extensions. Keep `init?(pollingOption:delegate:queue:)` behind an
+availability check while the deployment target is below 26.4.
+
+```swift
+@available(iOS 26.4, *)
+func makeTransitSession(delegate: any NFCTagReaderSessionDelegate) -> NFCTagReaderSession {
+    let config = NFCTagReaderSession.Configuration(
+        pollingOption: [.iso14443, .iso18092],
+        iso7816SelectIdentifiers: ["A000000000000001"],
+        feliCaSystemCodes: []
+    )
+    return NFCTagReaderSession(configuration: config, delegate: delegate, queue: nil)
+}
+
+@available(iOS 26.4, *)
+func pollOnlyFeliCa(_ session: NFCTagReaderSession) {
+    session.restartPolling(configuration: .init(pollingOption: .iso18092))
+}
+```
+
 ## Writing NDEF
 
 Query the status first. Only `.readWrite` tags accept a write; anything else

package/pipeline/skills/shared/external/ios-coding-standard/references/rules.yml

@@ -457,7 +457,7 @@ rules:
       Scene, ViewModel, AnalyticsTracking, UseCase, Repository (+protocol +mock), Mapper +
       models  -  each present when its responsibility exists. In a converted module the screen's
       Output enum lives contract-side, not here, and a module-local CoordinatorEvent or
-      LocalizedText aggregator is pre-conversion residue reported as debt. Report a missing file
+      copy aggregator (`<Screen>Copy`) is pre-conversion residue reported as debt. Report a missing file
       whose responsibility leaked elsewhere AND a ceremonial empty file.
 
   - id: STRUCT-03
@@ -1129,7 +1129,7 @@ rules:
             "**/*+Modifiers.swift",
           ],
       }
-    scope_reason: SwiftUI copy surface (LocalizedText); UIKit modules localise through a different seam
+    scope_reason: SwiftUI copy surface (`<Screen>Copy`); UIKit modules localise through a different seam
     title: All user copy goes through the screen's copy surface
     severity: important
     enforcement: judgement

package/pipeline/skills/shared/external/ios-module-structure/modules/_TEMPLATE.yml

@@ -85,7 +85,7 @@ roles:
 #    screen.viewmodelaction:  "Presentation/Models/*ViewModelAction.swift"
 #    screen.viewmodelstate:   "Presentation/Models/*ViewModelState.swift"
 #  Multi-target packages (STRUCT-21):
-#    target.configurator:     "Sources/*/Configuration/*DependencyConfigurator.swift"
+#    target.configurator:     "Sources/*/Configuration/*DependencyRegistrar.swift"
   screen.root: # e.g. "Sources/*/Screens/*"
   screen.entry:
   screen.viewmodel:

package/pipeline/skills/shared/external/localization-reuse-map/SKILL.md

@@ -32,7 +32,7 @@ Nothing company-specific is built in. Establish these once per project (read the
 | Specs repo + design export | Screen frames, `components-used.md`, `screenshot.png`, `tree.json` | `design-export/<project>/screens/<slug>/` |
 | Resources root | Suggested new values and the component registry | `resources/Localization/Suggested/<Key>.json` |
 | Legacy label endpoint | For refreshing the legacy snapshot | `--endpoint` + `--headers-file` |
-| Legacy key prefix | Display-only prefix the backend stores | mapping `legacyKeyPrefix`, e.g. `Mobile-` |
+| Legacy key prefix | Display-only prefix the backend stores | mapping `legacyKeyPrefix`, e.g. `App-` |
 | Web i18n convention | For legacy and/or new web apps | `t('key')` / `$t('key')`, keys in `locales/<lang>.json` |
 | Confluence target | Base URL, space, parent page | `CONFLUENCE_BASE_URL` / `CONFLUENCE_SPACE` / `CONFLUENCE_PARENT` |
 | CMS taxonomy | Property Group / Module buckets in the spreadsheet | `--taxonomy cms-taxonomy.json` |
@@ -51,7 +51,7 @@ After the screen spec exists: screen spec, then this map, then publish. If the r
 The helpers in `scripts/` use nothing beyond the Python 3 standard library, apart from one bash script. Commands and how each source is traced are covered in [sources-and-recipes](reference/sources-and-recipes.md).
 
 1. **Enumerate new keys.** Take the union of three sources: the design export's `components-used.md` across every state frame, each component's registry `localizationKeys`, and the keys the screen code wires. Tag each key screen-specific, component-owned or shared. Every key is confirmed by comparing sources, never lifted from one of them.
-2. **Catch what the cross-reference misses.** Run `scan-screen-keys.py --screen-path <dir>`. Each `error` and `dynamic` hit becomes a mapping row; compare the `static` hits with the union from step 1.
+2. **Catch what the cross-reference misses.** First find the type the project generates its keys into (for example `grep -rhoE '\b[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*\.[A-Za-z_]+' <dir> | cut -d. -f1 | sort | uniq -c | sort -rn`) and set it as `"keyType"` in the mapping; the built-in default `L10n` is only a fallback, and a project that uses another accessor gets its real keys missed or downgraded to weak. Then run `scan-screen-keys.py --screen-path <dir> --key-type <KeyType>`. A `WARNING: no key chain of ...` line on stderr means the type is wrong: fix it before going on. Each `error` and `dynamic` hit becomes a mapping row; compare the `static` hits with the union from step 1.
 3. **New values.** Run `resolve-new-values.py --keys "<all>" --resources-root <res> --langs all --catalog <shipped catalog>`; `--catalog` is never optional.
 4. **CMS copy.** Run `fetch-annotations.py --mapping <map>.json [--local <export-screen-dir>]`: it reads REST and falls back to `--local` when REST fails. When REST is rate-limited or has no token, dump the annotations through Figma MCP and run it again with `--from-mcp <dump>.json`. Fill `cms` and `cmsNodeId` on each row, and send any TR without EN back to the content team.
 5. **Trace legacy keys** per platform: spec, then view controller, view model and cell presentation models on iOS; layout `@string/` on Android; call sites on web.
@@ -61,7 +61,7 @@ The helpers in `scripts/` use nothing beyond the Python 3 standard library, apar
 9. **Key screenshots.** Run `render-key-shots.py --out <dir> --mapping <map>.json [--slug]`; it fills `keyshots/` and writes the manifest, which the mapping's `keyshots` field then names.
 10. **Artifacts.** `build-artifact.py <map>.json --out <dir>` (add `--docx`, `--pdf` or `--all` on request).
 11. **Spreadsheet.** `build-spreadsheet.py <map>.json --out <dir>` (add `--csv` or `--csv-only`).
-12. **Gate.** Run `verify-map.py --screen-path <dir> --mapping <map>.json [--resources-root <res>]`. Exit code 2 stops publishing.
+12. **Gate.** Run `verify-map.py --screen-path <dir> --mapping <map>.json [--resources-root <res>]`, with the accessor from step 2 in the mapping's `keyType` (or passed as `--key-type <KeyType>`). Exit code 2 stops publishing. A PASS that carries the key type `WARNING` is not a pass: set the accessor and run it again.
 13. **Publish.** Ask which target(s): (A) Confluence via `publish-confluence.py`, (B) a specs-repo PR under `localizations/<slug>/`, or both. Details: [publish-and-snapshot](reference/publish-and-snapshot.md).
 
 When the Figma frame carries no annotations, say so, explain that keys will be mapped by reading the screen, and confirm the screen state (mock or screenshot) and the anchored element list with the user before rendering.

package/pipeline/skills/shared/external/localization-reuse-map/example-mapping.json

@@ -6,7 +6,8 @@
   "screenshot": "screenshot.png",
   "overlay": "sign-up-account-details.overlay.png",
   "keyshots": "sign-up-account-details.keyshots.manifest.json",
-  "legacyKeyPrefix": "Mobile-",
+  "legacyKeyPrefix": "App-",
+  "keyType": "L10n",
   "rows": [
     {
       "element": "Screen title (top bar)",

package/pipeline/skills/shared/external/localization-reuse-map/reference/format-and-output.md

@@ -16,6 +16,7 @@ Top level:
 | `overlay` | no | Overlay PNG name |
 | `keyshots` | no | Keyshots manifest name |
 | `legacyKeyPrefix` | no | Prepended to legacy keys for display only |
+| `keyType` | no | The project's key accessor type, a string or a list of strings (for example `"Strings"` or `["Strings", "A11y"]`); `verify-map.py` uses it when `--key-type` is not given, else `L10n`. Any other JSON type stops the gate with exit 2 |
 | `rows` | yes | One object per UI element |
 
 Row:
@@ -34,11 +35,11 @@ Row:
 | `note` | Reasoning, edge-case flags, `(owned by ...)`, "dynamic - enumerate at runtime" |
 | `propertyGroup`, `propertyModule` | Optional spreadsheet-only overrides |
 
-Keep `new` and `legacy` fully eight-keyed. The summary table shows old and new `en`/`tr` plus CMS `tr`/`en`; the details section shows all eight languages plus every CMS language present.
+Keep `new` and `legacy` keyed by every language the project ships. The summary table shows old and new `en`/`tr` plus CMS `tr`/`en`; the details section shows every language of the mapping (or the `--langs` list) plus every CMS language present.
 
 ### The example
 
-[`../example-mapping.json`](../example-mapping.json) maps a neutral "Sign Up - Account Details" screen in nine rows, with `legacyKeyPrefix: "Mobile-"`:
+[`../example-mapping.json`](../example-mapping.json) maps a neutral "Sign Up - Account Details" screen in nine rows, with `legacyKeyPrefix: "App-"`:
 
 | # | Case | Verdict |
 |---|---|---|
@@ -59,7 +60,7 @@ Keep `new` and `legacy` fully eight-keyed. The summary table shows old and new `
 | File | Contents |
 |---|---|
 | `<slug>.md` | Title, intro, platforms and Figma nodes, screenshot, optional key-map image, summary with counts, drift note, pipe table (pipes escaped, newlines flattened, keyshot as a relative image), per-row detail tables |
-| `<slug>.confluence.xml` | Storage format, the value of `body.storage.value`: header paragraph, an `info` macro with the legend (status macros), counts, CMS line and drift note; a Screen section (`<ac:image ac:height="500">`); a key-map section (`<ac:image ac:width="900">`); the summary table with keyshots (`<ac:image ac:width="240">`) referenced by attachment name, keys in `<code>`, status macros; per-row details with an eight-language Old / New / CMS table |
+| `<slug>.confluence.xml` | Storage format, the value of `body.storage.value`: header paragraph, an `info` macro with the legend (status macros), counts, CMS line and drift note; a Screen section (`<ac:image ac:height="500">`); a key-map section (`<ac:image ac:width="900">`); the summary table with keyshots (`<ac:image ac:width="240">`) referenced by attachment name, keys in `<code>`, status macros; per-row details with an Old / New / CMS table per language |
 | `<slug>.preview.html` | Standalone page with sections 1 Screen, 2 Summary, 3 Details and coloured verdict badges. Absolute image paths become `file://` URLs; bare names stay relative |
 | `<slug>.docx` (`--docx`) | Word document built with the standard library: landscape A4, screenshot, overlay and keyshot thumbnails, verdict-shaded cells, a pink cell for drifting CMS TR, right-to-left Arabic rows |
 | `<slug>.pdf` (`--pdf`) | LibreOffice from the docx, then headless Chrome from the preview, then `wkhtmltopdf`. With none of them installed the PDF is skipped with a note naming the file to share instead |
@@ -96,7 +97,7 @@ Nine fixed columns, spelled exactly like this:
 
 | Check | Hard? |
 |---|---|
-| Each `newKey` is wired in the screen code (exact match), or exempt as component-owned or dynamic. A `LocalizationStringKey` chain counts as a key only with two or more segments, so `extension LocalizationStringKey.Checkin` is not one. A key whose last segment only appears as a word is `weak`; neither is `unverified` | unverified: hard |
+| Each `newKey` is wired in the screen code (exact match), or exempt as component-owned or dynamic. A chain of the key type (`--key-type`, default `L10n`) counts as a key only with two or more segments, so `extension L10n.Profile` is not one. A key whose last segment only appears as a word is `weak`; neither is `unverified`. When no chain of the key type is found but Swift or Kotlin code has chains rooted at a common accessor name or ending in `.localized`, a `keyTypeWarning` names those roots; set the key type and rerun | unverified: hard |
 | Keys the code wires that no row maps (`codeKeysNotInMap`) | hard |
 | `reuse` / `review` row without any legacy `en` or `tr` value | hard |
 | Non-`new` row with an empty or whitespace-only `new.tr` | soft |
@@ -109,17 +110,17 @@ A row is component-exempt when its `newKey` carries a marker naming the owner: `
 
 | Script | Key flags |
 |---|---|
-| `scan-screen-keys.py` | `--screen-path` (required), `--out`, `--category all/error/dynamic/static` |
-| `resolve-new-values.py` | `--keys`, `--keys-file` (`-` for stdin), `--resources-root` or `--suggested-dir`, `--domain localization/accessibility`, `--catalog`, `--report-source`, `--langs` (default `en,tr`, or `all`) |
-| `resolve-legacy-values.py` | `--keys` (required), `--langs`, `--snapshot-root`, `--live`, `--endpoint`, `--header K=V`, `--headers-file`, `--env`, `--status-field`, `--fail-status CODE=message`, `--timeout`, `--plist-root`, `--prefix` |
+| `scan-screen-keys.py` | `--screen-path` (required), `--out`, `--category all/error/dynamic/static`, `--key-type` (repeatable or comma list, default `L10n`) |
+| `resolve-new-values.py` | `--keys`, `--keys-file` (`-` for stdin), `--resources-root` or `--suggested-dir`, `--domain localization/accessibility`, `--catalog`, `--report-source`, `--langs` (default `all`) |
+| `resolve-legacy-values.py` | `--keys` (required), `--langs` (default `all`), `--snapshot-root`, `--live`, `--endpoint`, `--header K=V`, `--headers-file`, `--env`, `--status-field`, `--fail-status CODE=message`, `--timeout`, `--plist-root`, `--prefix` |
 | `fetch-legacy-labels.py` | `--out`, `--endpoint` (both required), `--header`, `--headers-file`, `--langs` (default `all`), `--env`, `--status-field`, `--fail-status`, `--timeout` |
-| `fetch-annotations.py` | `--file`, `--nodes`, `--mapping`, `--from-mcp`, `--local`, `--source auto/rest/mcp/local`, `--token`, `--ca-file`, `--out` |
-| `render-overlay.py` | `--mapping` (required), `--spec`, `--file`, `--nodes`, `--scale`, `--token`, `--ca-file`, `--out`, `--slug`, `--ui-lang en/tr` |
-| `render-key-shots.py` | `--mapping` (required), `--spec` (repeatable), `--file`, `--nodes`, `--pad` (default 150), `--scale`, `--token`, `--ca-file`, `--out`, `--slug` |
-| `build-artifact.py` | `mapping` (or `-`), `--out`, `--slug`, `--ui-lang en/tr`, `--docx`, `--pdf`, `--all`, `--print-upload` |
+| `fetch-annotations.py` | `--file`, `--nodes`, `--mapping`, `--from-mcp`, `--local`, `--source auto/rest/mcp/local`, `--ca-file`, `--out` |
+| `render-overlay.py` | `--mapping` (required), `--spec`, `--file`, `--nodes`, `--scale`, `--ca-file`, `--out`, `--slug`, `--ui-lang en/tr` |
+| `render-key-shots.py` | `--mapping` (required), `--spec` (repeatable), `--file`, `--nodes`, `--pad` (default 150), `--scale`, `--ca-file`, `--out`, `--slug` |
+| `build-artifact.py` | `mapping` (or `-`), `--out`, `--slug`, `--ui-lang en/tr`, `--docx`, `--pdf`, `--all`, `--print-upload`, `--langs` (default `all`) |
 | `build-spreadsheet.py` | `mapping` (or `-`), `--out`, `--slug`, `--channel`, `--taxonomy`, `--csv`, `--csv-only` |
-| `verify-map.py` | `--mapping`, `--screen-path` (both required), `--resources-root`, `--out` |
+| `verify-map.py` | `--mapping`, `--screen-path` (both required), `--resources-root`, `--out`, `--key-type` (else the mapping's `keyType`, else `L10n`) |
 | `publish-confluence.py` | see [publish-and-snapshot](publish-and-snapshot.md) |
 | `snapshot-resources.sh` | `<resources-root> <specs-root>` |
 
-`all` languages means `en, tr, ar, de, es, fr, it, ru` in every script. Every script derives the same slug from `screen`: lowercase, each run of non-letter, non-digit characters becomes one `-`, leading and trailing dashes trimmed, `screen` when nothing is left. `--slug` overrides it on any script. Figma tokens resolve from `--token`, then `FIGMA_ACCESS_TOKEN`, then `FIGMA_TOKEN`, then the macOS keychain item `FIGMA_ACCESS_TOKEN`; prefer the environment or keychain, since argv is visible to other processes.
+`--langs` takes a comma list, used in the order given, or `all`: every language present in the data the script reads (the mapping rows, the Suggested files and catalog, the snapshot or plist folder, or for `fetch-legacy-labels.py` the snapshot it refreshes), `en` first and the rest sorted, and `en` alone when the data names none. Every script derives the same slug from `screen`: lowercase, each run of non-letter, non-digit characters becomes one `-`, leading and trailing dashes trimmed, `screen` when nothing is left. `--slug` overrides it on any script. Figma tokens resolve from `FIGMA_ACCESS_TOKEN`, then `FIGMA_TOKEN`, then the macOS keychain item `FIGMA_ACCESS_TOKEN`. `--token` is refused with exit 2, since argv is visible to other processes.

package/pipeline/skills/shared/external/localization-reuse-map/reference/publish-and-snapshot.md

@@ -51,8 +51,8 @@ python3 scripts/publish-confluence.py \
 
 - **Target**: `--base` / `--base-url`, `--space` and `--parent`, or the variables `CONFLUENCE_BASE_URL`, `CONFLUENCE_SPACE` and `CONFLUENCE_PARENT`.
 - **Title**: `--title` when given; otherwise `<prefix> - <screen>`, with the prefix taken from `--title-prefix`, then `LOCALIZATION_PAGE_PREFIX`, then the default `Localization`.
-- **Token**: a Server / Data Center personal access token, sent as a Bearer header. The script tries `--token`, then `CONFLUENCE_API_TOKEN`, then the macOS keychain service given by `--keychain-name` (default `CONFLUENCE_API_TOKEN`). Use the keychain where possible, because other processes can read argv.
-- **Transport**: `curl` carries every request. The Authorization header is written to a temporary config file with mode 600, handed over with `-K` and removed at the end; JSON bodies also travel through a temporary file.
+- **Token**: a Server / Data Center personal access token, sent as a Bearer header. The script reads `CONFLUENCE_API_TOKEN`, then the macOS keychain service given by `--keychain-name` (default `CONFLUENCE_API_TOKEN`). `--token` is refused with exit 2, because other processes can read argv.
+- **Transport**: `curl` carries every request. The Authorization header is written to a temporary config file with mode 600, handed over with `-K` and removed at the end; JSON bodies also travel through a temporary file. Each request is bounded: `--connect-timeout 15` and `--max-time 120` for curl, and the script stops waiting for curl after 150 seconds.
 - **Idempotent**: the lookup is `GET /rest/api/content?spaceKey=&title=&type=page&expand=version&limit=5`, which reads the database rather than the CQL index. A hit is updated with `PUT` and the next version number, reported as `updated (vN->vN+1)`; a miss is created with `POST` below the parent and reported as `created`. A second run lands on the same page id.
 - **Attachments**: the screenshot first, then the overlay, then each `.png` listed in the keyshots manifest, then every `--attach` file. When a file of that name is already attached, a new version is uploaded to `.../child/attachment/<id>/data` instead of adding a second copy.
 - **Inline spreadsheet**: an `--attach` file with the extension `.xlsx`, `.xls`, `.csv`, `.docx` or `.pdf` is additionally shown on the page: a heading is appended (`--embed-heading`, default "CMS Import File"; pass the team's own wording, for example a Turkish title, to change it), then one `view-file` macro per such file.

package/pipeline/skills/shared/external/localization-reuse-map/reference/sources-and-recipes.md

@@ -21,25 +21,25 @@ A screen's keys come from three places, and each one misses something the others
 
 1. **Design export**: read `screens/<frame>/components-used.md` of each state frame the screen has (default, error, loading, filled...).
 2. **Component registry**: each used component's `<node>.json -> localizationKeys`. These are keys the component renders internally, and they are often absent from the screen code.
-3. **Screen code**: on iOS, each call site of `LocalizationStringKey.<Namespace>.<leaf>` counts as one element.
+3. **Screen code**: on iOS, each call site of `<KeyType>.<Namespace>.<leaf>` counts as one element, where `<KeyType>` is the type the project generates its keys into. Pass it to `scan-screen-keys.py` and `verify-map.py` with `--key-type <Name>` (repeatable, or a comma list), or set `"keyType"` in the mapping for `verify-map.py`; the default is `L10n`.
 
 Take the union and tag every key: screen-specific, component-owned, or shared (a reusable component or a shared primitive).
 
-Registry caveat: a shared component such as `HeaderMain` or `BottomActions` may list keys that this screen never shows, since the screen supplies its own title. Check the code before a registry key goes into the map.
+Registry caveat: a shared component such as `ScreenHeader` or `ActionFooter` may list keys that this screen never shows, since the screen supplies its own title. Check the code before a registry key goes into the map.
 
 ### Keys the union cannot see
 
 Error, validation and alert strings, and keys assembled at runtime, rarely appear in the design export or the registry. Run the scanner on the implemented screen:
 
 ```bash
-python3 scripts/scan-screen-keys.py --out scan.json --screen-path <screen-dir>
+python3 scripts/scan-screen-keys.py --out scan.json --screen-path <screen-dir> --key-type <KeyType>
 ```
 
 Every `error` and `dynamic` hit becomes a row. Compare the `static` hits with the union; whatever remains is a key the code wires but the map lacks. Skipping this step drops those strings silently.
 
 ## New values
 
-Values are authored per key in `Suggested/<Key>.json`, in eight languages, and they are shared by all platforms: one value per key, only the key usage differs per platform.
+Values are authored per key in `Suggested/<Key>.json`, one entry per language the project ships, and they are shared by all platforms: one value per key, only the key usage differs per platform.
 
 ```bash
 python3 scripts/resolve-new-values.py --keys "<k1>,<k2>" --resources-root <res> --langs all \
@@ -88,14 +88,14 @@ The same element can carry different keys per platform (`AgentaUserAlreadyAdded`
 
 ```bash
 python3 scripts/resolve-legacy-values.py --keys "Continue,EmailAddress" \
-  --snapshot-root resources/Localization/Legacy --langs all --prefix Mobile-
+  --snapshot-root resources/Localization/Legacy --langs all --prefix App-
 ```
 
 - Reading the snapshot needs no network. `fetch-legacy-labels.py` refreshes it and is the only step that goes online.
 - `--live` checks against the service directly; if the live call fails, the script falls back to the snapshot, then to the plists.
 - With none of `--snapshot-root`, `--plist-root` or `--endpoint`, the script stops with a message naming them.
 - `--plist-root` reads the bundled `<lang>.lproj/language.plist` as a last resort. It is usually a stale subset, so a hit from it deserves a note.
-- **Backend prefix.** When the backend stores `Mobile-Continue` but the app asks for `Continue`, pass `--prefix Mobile-`, keep the mapping keys bare, and set the mapping's `legacyKeyPrefix` so the table shows the full stored key.
+- **Backend prefix.** When the backend stores `App-Continue` but the app asks for `Continue`, pass `--prefix App-`, keep the mapping keys bare, and set the mapping's `legacyKeyPrefix` so the table shows the full stored key.
 
 ## Overlay geometry
 
@@ -138,5 +138,5 @@ Geometry reuses the overlay inputs: REST (visible text only, filtered for ancest
 - **Stale snapshot.** Missing from Suggested is not unauthored; pass `--catalog` and refresh the snapshot instead of filing requests.
 - **Value anchoring.** Never anchor a keyshot by value across a whole file: short labels recur on unrelated screens and give a confidently wrong crop, which is worse than a dash. Recover a row only through its own `cmsNodeId`, and leave `characters` out of nodes handed to `render-key-shots.py --spec`, because text present turns value matching back on and can bind an unrelated row.
 - **Confluence auth.** Server / Data Center takes a Bearer PAT (keychain `CONFLUENCE_API_TOKEN`), not the Cloud `user:token` form. Pages are looked up with the `content?title=` query, which reads the database; CQL is avoided because its index lags and leads to duplicate pages.
-- **Secrets.** Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or the docs.
+- **Secrets.** Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or the docs. No script takes a token on the command line: `--token` exits 2, because other processes can read argv. Use the environment variable or the keychain item each script names.
 - **TLS proxies.** Publishing runs through `curl` so a corporate proxy's trust store is honoured (Python `urllib` fails verification there). The token goes in a `chmod 600` config passed with `-K`, never on argv. For the Figma scripts behind such a proxy, export the system roots with `security find-certificate -a -p > roots.pem` and pass `--ca-file roots.pem`.