Skip to content

fix: admit approved global steering symlinks - #14007

Open
vinayshah1998 wants to merge 3 commits into
kirodotdev:mainfrom
vinayshah1998:fix/guarded-steering-roots-20260925
Open

vinayshah1998 wants to merge 3 commits into
kirodotdev:mainfrom
vinayshah1998:fix/guarded-steering-roots-20260925

Conversation

@vinayshah1998

@vinayshah1998 vinayshah1998 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Crew mode rejects symlinked global steering with linked document or directory. Members cannot load shared steering from its canonical source, even when the document is readable.

Why it matters

Users need one source of truth. Copying steering documents creates duplicates that drift and require synchronization.

What changed

Global steering leaf links can load only when protected host policy or a host-bound profile explicitly permits the resolved target.

global steering link
  -> validate canonical target
  -> steering.sources policy + host profile
  -> exact-file pinned read
  -> member context under the logical source name
  • Add the opt-in steering.sources ruleset. Missing approval denies in enforcement, policy explanations, and the Security page.
  • Apply the same admission rule to literal and wildcard resource patterns.
  • Preserve sensitive-file and managed-memory exclusions, ancestor checks, exact-file confinement, file-type checks, and size limits. Directory links and project links outside global steering remain refused.
  • Preserve logical names and conditional triggers. No copied-source or synchronization mechanism.

Pending revision

The following fixes are prepared locally but are NOT in the published head: audited ruleset decisions through vet_and_audit, portable Windows test patterns, module-level imports, corrected contract documentation, and an explanatory InfoTip beside "Nothing allowed". Publishing requires folding them into the existing two commits, subject to approval for a lease-guarded force-push. Review blockers remain open until publication and CI verification.

Backwards compatibility

Compatible. Omitting the new scope continues to refuse links. Existing scopes retain their behavior. Older versions reject a policy naming the new scope, so upgrade before configuring it.

Tests

  • Published head: 908 targeted backend tests and 106 SecurityPanel tests passed locally, with builds and static checks. The broader backend run had 80,021 passes and one PDF-extraction failure. That file passed in isolated candidate and clean-base runs; the load failure was not proved to be a baseline bug.
  • Published CI remains red on 48 Windows test-path failures and one unrelated Linux thread-race test. Coverage failure follows those shards. Real Windows verification awaits the repaired head.
  • Local pending revision: 1,036 targeted backend tests, 107 SecurityPanel tests, builds, and static checks passed. The selected local gate passed 80,296 backend and 10,169 frontend tests. Final documentation corrections were followed by refreshed backend tests, compile, formatting, lint, type, and documentation checks. This is not a full-suite CI pass.

Manual verification

The candidate production bundle passed 42 Playwright assertions with controlled governance API responses. Both governance states, keyboard activation, and 390px layout passed. This verifies rendering, not live host approval. Windows path behavior was emulated, not executed on Windows.

Screenshots / video

Candidate screenshots are captured for the ungoverned row, its InfoTip, and the governed policy row. Attachment is pending publication of that revision. No screenshot exemption is claimed.

Related Issues

None. The reported loader failure is described above.

Pattern harvest

Not generalizable: the repository already requires audited governance decisions. This revision applies that existing rule and adds allow, deny, and audit-failure regression coverage rather than proposing another broad lint rule.

Limits

Approval governs Crew-managed essentials, not independent native CLI readers. Either explicitly configured host-controlled tier can grant; an explicit empty allow-set in the ceiling keeps access closed. Windows junctions and macOS case-only aliases remain unqualified. No running installation or live approval has changed.

Checklist

  • At most two commits and a Conventional Commits title.
  • All CI checks pass. Repaired head not yet published.
  • New behavior has regression coverage.
  • Code and documentation reviewed.
  • No secrets or internal references in the diff.

@vinayshah1998
vinayshah1998 requested review from a team and cixuuz September 25, 2026 22:59
@dwu96

dwu96 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR's description is missing some required sections from our PR template. Workflow runs won't be auto-approved until the description is updated.

Missing sections:

  • ## Problem / Motivation
  • ## Why it matters
  • ## What changed
  • ## Tests

Please update your PR description to include these sections, then push or re-save the description. The workflows will be approved on the next cycle.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🔴 BLOCK

UX-level review of edab1a7f3d89a3e7a10a63f35dc175f644d36c6f via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: BLOCK

Cannot evaluate: missing a screenshot of the Security page governance section showing the new "Linked steering sources" row.

Watch

  • "Nothing allowed" on the ungoverned row ships with no explanation or next step: GovernanceRow's ungoverned branch renders only the muted italic {label} span (no InfoTip, unlike governed rows), so every user on a default install sees "Linked steering sources — Nothing allowed" with no way to learn it's an opt-in they haven't lost. Frequency: every Security-page visit; impact: confusion/false alarm; persistence: permanent until opt-in. Smallest fix: render an InfoTip on the deny_when_ungoverned branch explaining the opt-in and where it's granted.
  • The refusal string f"{STEERING_SOURCES_SCOPE} does not permit linked target {canonical!r} ({reason})" names the mechanism but not the repair, and renders a bare () when reason is empty; the operator whose crew fails to build gets no pointer to security_policy.json. Add the remedy and drop the empty parenthetical.

Evidence gaps

  • The "Linked steering sources" governance row in its default ungoverned "Nothing allowed" state (SecurityPanel.tsx, effectiveLabel) — image list and recording list are both empty; closed by attaching a Security → Governance screenshot of a default install, or committing one under temp-screenshots/.
  • The same row governed (Lock icon, source badge, allow-list label) — closed by a screenshot with a steering.sources ruleset in effect.

[UX-REVIEWED] edab1a7

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🔴 BLOCK (blocking)

Design-level review of edab1a7f3d89a3e7a10a63f35dc175f644d36c6f via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: BLOCK

Cannot evaluate: missing screenshot of the Security panel's new "Linked steering sources — Nothing allowed" governance row; backend design itself is sound.

Blockers

Missing rendered evidence for a reshaped Security panel
The diff changes what every user sees by default — a new steering.sources row in the io plane and a new ungoverned state (GovernanceRow now renders label, which can be "Nothing allowed") — and the evidence file records "attachments downloaded and typed as images: 0" and no committed images, so whether the row reads as intended (and not as "steering is off", the exact confusion the PR's own comment guards against) cannot be judged from code alone.
Fix: attach a screenshot of the governance section showing the new row in both its ungoverned ("Nothing allowed") and governed states at this revision.
Clears when: the PR description carries a downloadable image (or a committed image under temp-screenshots/ or .github/screenshots/) of the SecurityPanel governance list rendered from this revision.

[DESIGN-REVIEWED] edab1a7

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of edab1a7f3d89a3e7a10a63f35dc175f644d36c6f via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

An opt-in capability shipped as fix: — the base spec pins link refusal as deliberate, and the need rests on the description alone, no linked issue.

Not justified as shipped

  • Item 1 — inherited: the "Problem" ("Crew mode rejects symlinked global steering") describes behaviour the base spec pins on purpose ("a document that is, or sits under, a link below the root is still refused", memory-skills-hooks.md:1309); the requirement's only provenance is the description's own "Users need one source of truth for shared steering" — no linked issue, report, or recorded ask. The added test failing on base proves the refusal exists, not that it is a defect. Opt-in and default-deny keep this reversible, so it is advisory, but it is an ADDITION carried under a fix type.
    Clears when: a linked issue or user report naming who is maintaining drifting steering copies, or a maintainer accepts it as a feature.

Everything else holds up under counting: no existing mechanism reads an external canonical file (absolute resources outside the admitted roots are refused, member_essential_context.py:174), deny_when_ungoverned as catalog metadata is mandated by the scope-name-agnostic-evaluator invariant in AGENTS.md, the location-decides rule is the cause-level shape (a wildcard-only patch would leave the literal-component sibling in _matches unfixed), and specs update in the same commit.

What this change ships

Inventory (7 items) — 6 justified

Intent: let members read shared global steering through symlinks from one canonical source, gated by explicit host approval — an ADDITION, despite the fix: title.

  1. Approved symlinks under ~/.kiro/steering now deliver their canonical target's content — inherited: need asserted only in the description
  2. New steering.sources policy/profile key an operator can author — justified
  3. Absent approval denies consistently (evaluator, governance_permits, policy explain) via catalog metadata — justified
  4. Security page gains a "Linked steering sources" row reading "Nothing allowed" when ungoverned — justified
  5. Literal-final glob components judge steering links by the same rule as wildcards — justified
  6. Refusal message for an unapproved global steering link now names steering.sources — undeclared
  7. Translated row label in 13 locales — rides along

[FIRST-PRINCIPLES-REVIEWED] edab1a7

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

Reviewed edab1a7f3d89a3e7a10a63f35dc175f644d36c6f via the fork AI-review pipeline; updated in place on each push.

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/member_essential_context.py:244 -- Steering authorization bypasses required SEL auditing

decision = governance_permits(
Linked steering source -> context builder -> authorization permit/deny -> no SEL governance event.
Anchor: backend-security-controls
Fix: Use vet_and_audit with a stable tool name.
FINDING -- src/kiro_crew/member_essential_context.py:231 -- Function-local from kiro_crew.platform.context import PlatformCompositionError violates top-level-imports -> Fix: move the three imports to module scope or document the circular-import exception. (origin: validation)
[BLOCK-MERGE] edab1a7
[GPT-REVIEWED] edab1a7

Adjudication (Opus 5) — is blocking on each finding proportionate?

Harm rung — unbounded-class as fenced (governance authorization without an audit record); conditions are ordinary, not extreme.
Confirmed: the new authorization at member_essential_context.py _admit_governed_steering_leaf calls bare governance_permits (patch src/kiro_crew/member_essential_context.py hunk @@ -188,8 +218,122 @@) and nothing on that path writes SEL — grep of the whole patch and of the base file finds no sel/log_governance_decision/vet_and_audit; governance_permits itself audits only its own degrade (src/kiro_crew/platform/governance_profiles.py:1193-1230, and docs/system-specs/modules/governance.md:1410), and AUTOSDE.yaml:40,69 (blocking: true) states permission decisions MUST emit a SEL event.
Real fix cost is small (swap to vet_and_audit with a fixed tool_name, per governance_profiles.py:1238), and the gap occurs on every admitted linked steering leaf rather than under a rare condition combination, so no rarity argument can be completed.

[ADJUDICATION] edab1a7 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] edab1a7
[ADJUDICATION-FENCED] edab1a7 fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/member_essential_context.py:244 -- The unaudited governance_permits authorization is on the ordinary admitted-link path, not a rare condition combination, and the blocking anchor rule expressly requires a SEL event for permission decisions.
[GPT-ADJUDICATED-FENCED] edab1a7

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — 🔴 changes requested (blocking)

Reviewed edab1a7f3d89a3e7a10a63f35dc175f644d36c6f via the fork AI-review pipeline; updated in place on each push.

BLOCKING — the new steering.sources authorization chokepoint writes no SEL audit record, violating blocking rule backend-security-controls.

BLOCKING — src/kiro_crew/member_essential_context.py:245

        decision = governance_permits(
            STEERING_SOURCES_SCOPE, str(canonical), session_key=HOST_SESSION_KEY, fail_closed=True
        )
        if not getattr(decision, "permitted", False):

~/.kiro/steering/shared.md -> /srv/standards/shared.md on any member turn → context.py:3770 documents_for_member → _matches → _judge_link → _admit_governed_steering_leaf (and again via _read → _read_governed_steering_leaf) → a grant or deny is produced and no sel().log_governance_decision is written on any part of the path (the module imports no sel; governance_permits audits only its degrade branch), so off-root bytes entering the model's context — and the denial that refuses the whole essentials build — leave no authorization record, while every peer chokepoint writes one (agent_backend_governance._audit, apps/manager.py:1865, governance_profiles.vet_and_audit).
Fix: inside _admit_governed_steering_leaf, after the decision, wrap a best-effort from kiro_crew.sel import sel; sel().log_governance_decision(session_key=HOST_SESSION_KEY, tool_name=f"steering_source:{logical}", scope=STEERING_SOURCES_SCOPE, item=str(canonical), outcome="allowed" if permitted else "denied", rule=..., layer=..., reason=...) in try/except for both branches.

FINDING — src/kiro_crew/platform/governance.py:1297 — the added STEERING_SOURCES_SCOPE: ScopeSpec(RULESET, matcher="path", deny_when_ungoverned=True) row contradicts the unedited contract comment immediately above SCOPE_CATALOG ("Omission means ungoverned-and-permitted for every archetype"), the one block the file marks "read before touching any capability_default", so a policy author reading it concludes omission cannot deny → Fix: amend that comment block in this commit to name the deny_when_ungoverned exception and the one row carrying it.

[BLOCK-MERGE] edab1a7
[OPUS-REVIEWED] edab1a7

@vinayshah1998

Copy link
Copy Markdown
Contributor Author

Thanks for the reviews. This comment covers the items that need no code and says where the code items stand. Nothing below claims a bot verdict resolved; those re-run on the next head.

Description sections (dwu96). The four required sections have been present since the earlier edit. This edit adds the rest of the template: Backwards compatibility, Manual verification, Screenshots / video, Related Issues, Pattern harvest, and the Checklist, and records the current state of CI on this head.

Title stays fix: (First Principles). The work was scoped as a repair of the linked-steering refusal whose remedy is an opt-in, default-deny scope, and the base-spec sentence it changes moves in the same diff. Rather than retitle to feat: to drop the gate, the description now carries the Pattern harvest section that PR Hygiene requires of fix PRs. No issue tracks the request; the motivation is stated in the description.

Bare () in the refusal (UX review, Watch). Not reachable on this head. Decision.reason is a required positional str on the frozen dataclass (governance.py L809-L810), and every denying constructor reachable from _admit_governed_steering_leaf passes a non-empty reason: ScopedRuleset.permits writes ... not in allow-set or ... matches deny pattern ... (L895-L903), _AndRuleset.permits prefixes policy: or profile: (L969-L976), ungoverned_decision writes ... is not named by any policy or profile; denied until one names it (L3889), and the fail-closed degrade writes ...; denied (fail-closed) (governance_profiles.py L1242). The getattr(decision, "reason", "") at member_essential_context.py L253 only defaults when the attribute is missing, which no Decision lacks. The message shape is unchanged.

Code findings: prepared locally, not on the remote. The SEL audit gap (GPT 5.6, Opus 5), the module-level imports, the CAPABILITY-DEFAULT CONTRACT comment, the InfoTip on the ungoverned "Nothing allowed" row, and the Windows test-pattern spelling behind the 48 shard-4 failures all have a prepared revision, verified locally as described under "Pending revision" in the description. Publishing it means amending the two existing commits and force-pushing with lease (two-commit cap), which waits on the branch owner's approval, so the bot verdicts on edab1a7f3 stand as written until the new head lands. The screenshots the UX and Design lanes ask for were captured from that revision and go into the description in the web UI after the push.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 26, 2026
@NicholasRBowers NicholasRBowers added needs-pr-triage PR scanner: awaiting automated triage drive-to-green PR claimed by drive-to-green pipeline and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 30, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author.

Assessment: Reviewers accept the design (Design Review calls the backend "sound"); every blocker is mechanical. The GPT and Opus BLOCKs are the same one defect — member_essential_context.py calls governance_permits with no SEL audit record, which the repo's own governance_profiles.vet_and_audit helper closes. All 48 Windows failures are in this PR's own new test file, which builds allow patterns as f"{tree.external}/*.md" and so mixes separators on Windows; str(tree.external / "*.md") plus re.escape on the pytest.raises(match=...) paths fixes them. Design and UX BLOCK only as "cannot evaluate" for missing screenshots, so Screenshot Evidence and both lanes clear with captures of the Security → Governance row. Remaining items: move the function-local imports in _admit_governed_steering_leaf to module scope, name the deny_when_ungoverned exception in the CAPABILITY-DEFAULT CONTRACT comment, add the ungoverned-row InfoTip, and rebase (678 commits; GovernanceScope now lives in website/src/api/client/security.ts after #14563).

Note: on 2026-09-26 you mentioned a local revision addressing the code findings was ready but not pushed — the head here is still edab1a7f from 09-25. If you push it, I'll rebase onto your work rather than duplicate it.

If you'd prefer I don't touch this PR, add the pr-no-autofix label.

@bolichen97

Copy link
Copy Markdown
Contributor

Overlap note from #16263 (symlinked-home member sources, fixes #16255): that PR touches member_essential_context.py but not _read or _matches. It adds _read_implicit_guide / _omitted_guide and changes only the project-root AGENTS.md / SOUL.md loop in documents_for_member, so that a refusal there becomes an in-band omission instead of failing the turn. Containment is unchanged: links outside the project stay refused. The global-steering leaf-link admission here is not duplicated, and the two should rebase cleanly against each other. Only add() gains an optional body= parameter.

Copy link
Copy Markdown
Contributor

PR triage (automated, 2026-10-05): REBASE + CONTINUE-DEVELOPMENT

I compared head edab1a7f with origin/main cc7e7989. The branch is 1,590 commits behind its merge base 07a05a2b, and git merge-tree reports content conflicts in three files:

Relationship to other PRs:

Open blockers on this head (already raised, not repeated here as new findings):

  • The new steering.sources decision is not SEL-audited. The fix is to route it through vet_and_audit, as both the GPT and Opus reviews say.
  • The Windows path failures are in the new test file.
  • The "Omission means ungoverned-and-permitted" contract comment above SCOPE_CATALOG needs to mention the deny_when_ungoverned exception.

The "pending revision" mentioned in the description has not been pushed yet. Please push it onto a branch rebased on current main.

vinayshah1998 and others added 3 commits October 19, 2026 17:29
Pin single-source steering delivery, default-deny diagnostics, and
filesystem isolation across the member and native capture paths.

The authorized-link checks fail against the previous loader.
Read shared steering from its canonical source without copied files.
Use protected host policy and profile rules to authorize linked targets,
and preserve exact-file confinement, memory isolation, and input limits.

Preserve implicit link omissions and declared escape refusals. Screen
metadata before classifying an unselected link, without reading its
contents, traversing its target, or authorizing an unselected source.
Audit grants and denials through the existing signed SEL seam.

Use pysqlite3 0.6.x to avoid the bundled SQLite WAL open/close deadlock.
Require Linux glibc 2.28, validate compatible dependency wheels in CI,
and keep install guidance aligned with the selected distribution.
Linux systems with glibc older than 2.28 are no longer supported.

Amp-Thread-ID: https://ampcode.com/threads/T-01a15526-7ea0-7558-b252-e0dc869fc0fa
Use the empty-array-safe expansion required by the workflow
compatibility gate while preserving the generated platform arguments.

Amp-Thread-ID: https://ampcode.com/threads/T-01a15526-7ea0-7558-b252-e0dc869fc0fa
@vinayshah1998
vinayshah1998 force-pushed the fix/guarded-steering-roots-20260925 branch from edab1a7 to 604d9a3 Compare October 27, 2026 21:36

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

drive-to-green PR claimed by drive-to-green pipeline fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants